0001: /*
0002: * Copyright 2001-2005 The Apache Software Foundation
0003: *
0004: * Licensed under the Apache License, Version 2.0 (the "License");
0005: * you may not use this file except in compliance with the License.
0006: * You may obtain a copy of the License at
0007: *
0008: * http://www.apache.org/licenses/LICENSE-2.0
0009: *
0010: * Unless required by applicable law or agreed to in writing, software
0011: * distributed under the License is distributed on an "AS IS" BASIS,
0012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0013: * See the License for the specific language governing permissions and
0014: * limitations under the License.
0015: */
0016: package org.apache.commons.net.ftp;
0017:
0018: import java.io.BufferedInputStream;
0019: import java.io.BufferedOutputStream;
0020: import java.io.BufferedReader;
0021: import java.io.IOException;
0022: import java.io.InputStream;
0023: import java.io.InputStreamReader;
0024: import java.io.OutputStream;
0025: import java.net.InetAddress;
0026: import java.net.ServerSocket;
0027: import java.net.Socket;
0028: import java.util.Vector;
0029:
0030: import org.apache.commons.net.MalformedServerReplyException;
0031: import org.apache.commons.net.ftp.parser.DefaultFTPFileEntryParserFactory;
0032: import org.apache.commons.net.ftp.parser.FTPFileEntryParserFactory;
0033: import org.apache.commons.net.ftp.parser.ParserInitializationException;
0034: import org.apache.commons.net.io.CopyStreamEvent;
0035: import org.apache.commons.net.io.CopyStreamException;
0036: import org.apache.commons.net.io.FromNetASCIIInputStream;
0037: import org.apache.commons.net.io.ToNetASCIIOutputStream;
0038: import org.apache.commons.net.io.Util;
0039:
0040: /***
0041: * FTPClient encapsulates all the functionality necessary to store and
0042: * retrieve files from an FTP server. This class takes care of all
0043: * low level details of interacting with an FTP server and provides
0044: * a convenient higher level interface. As with all classes derived
0045: * from {@link org.apache.commons.net.SocketClient},
0046: * you must first connect to the server with
0047: * {@link org.apache.commons.net.SocketClient#connect connect }
0048: * before doing anything, and finally
0049: * {@link org.apache.commons.net.SocketClient#disconnect disconnect }
0050: * after you're completely finished interacting with the server.
0051: * Then you need to check the FTP reply code to see if the connection
0052: * was successful. For example:
0053: * <pre>
0054: * boolean error = false;
0055: * try {
0056: * int reply;
0057: * ftp.connect("ftp.foobar.com");
0058: * System.out.println("Connected to " + server + ".");
0059: * System.out.print(ftp.getReplyString());
0060: *
0061: * // After connection attempt, you should check the reply code to verify
0062: * // success.
0063: * reply = ftp.getReplyCode();
0064: *
0065: * if(!FTPReply.isPositiveCompletion(reply)) {
0066: * ftp.disconnect();
0067: * System.err.println("FTP server refused connection.");
0068: * System.exit(1);
0069: * }
0070: * ... // transfer files
0071: * ftp.logout();
0072: * } catch(IOException e) {
0073: * error = true;
0074: * e.printStackTrace();
0075: * } finally {
0076: * if(ftp.isConnected()) {
0077: * try {
0078: * ftp.disconnect();
0079: * } catch(IOException ioe) {
0080: * // do nothing
0081: * }
0082: * }
0083: * System.exit(error ? 1 : 0);
0084: * }
0085: * </pre>
0086: * <p>
0087: * Immediately after connecting is the only real time you need to check the
0088: * reply code (because connect is of type void). The convention for all the
0089: * FTP command methods in FTPClient is such that they either return a
0090: * boolean value or some other value.
0091: * The boolean methods return true on a successful completion reply from
0092: * the FTP server and false on a reply resulting in an error condition or
0093: * failure. The methods returning a value other than boolean return a value
0094: * containing the higher level data produced by the FTP command, or null if a
0095: * reply resulted in an error condition or failure. If you want to access
0096: * the exact FTP reply code causing a success or failure, you must call
0097: * {@link org.apache.commons.net.ftp.FTP#getReplyCode getReplyCode } after
0098: * a success or failure.
0099: * <p>
0100: * The default settings for FTPClient are for it to use
0101: * <code> FTP.ASCII_FILE_TYPE </code>,
0102: * <code> FTP.NON_PRINT_TEXT_FORMAT </code>,
0103: * <code> FTP.STREAM_TRANSFER_MODE </code>, and
0104: * <code> FTP.FILE_STRUCTURE </code>. The only file types directly supported
0105: * are <code> FTP.ASCII_FILE_TYPE </code> and
0106: * <code> FTP.IMAGE_FILE_TYPE </code> (which is the same as
0107: * <code> FTP.BINARY_FILE_TYPE </code>). Because there are at lest 4
0108: * different EBCDIC encodings, we have opted not to provide direct support
0109: * for EBCDIC. To transfer EBCDIC and other unsupported file types you
0110: * must create your own filter InputStreams and OutputStreams and wrap
0111: * them around the streams returned or required by the FTPClient methods.
0112: * FTPClient uses the {@link ToNetASCIIOutputStream NetASCII}
0113: * filter streams to provide transparent handling of ASCII files. We will
0114: * consider incorporating EBCDIC support if there is enough demand.
0115: * <p>
0116: * <code> FTP.NON_PRINT_TEXT_FORMAT </code>,
0117: * <code> FTP.STREAM_TRANSFER_MODE </code>, and
0118: * <code> FTP.FILE_STRUCTURE </code> are the only supported formats,
0119: * transfer modes, and file structures.
0120: * <p>
0121: * Because the handling of sockets on different platforms can differ
0122: * significantly, the FTPClient automatically issues a new PORT command
0123: * prior to every transfer requiring that the server connect to the client's
0124: * data port. This ensures identical problem-free behavior on Windows, Unix,
0125: * and Macintosh platforms. Additionally, it relieves programmers from
0126: * having to issue the PORT command themselves and dealing with platform
0127: * dependent issues.
0128: * <p>
0129: * Additionally, for security purposes, all data connections to the
0130: * client are verified to ensure that they originated from the intended
0131: * party (host and port). If a data connection is initiated by an unexpected
0132: * party, the command will close the socket and throw an IOException. You
0133: * may disable this behavior with
0134: * {@link #setRemoteVerificationEnabled setRemoteVerificationEnabled()}.
0135: * <p>
0136: * You should keep in mind that the FTP server may choose to prematurely
0137: * close a connection if the client has been idle for longer than a
0138: * given time period (usually 900 seconds). The FTPClient class will detect a
0139: * premature FTP server connection closing when it receives a
0140: * {@link org.apache.commons.net.ftp.FTPReply#SERVICE_NOT_AVAILABLE FTPReply.SERVICE_NOT_AVAILABLE }
0141: * response to a command.
0142: * When that occurs, the FTP class method encountering that reply will throw
0143: * an {@link org.apache.commons.net.ftp.FTPConnectionClosedException}
0144: * .
0145: * <code>FTPConnectionClosedException</code>
0146: * is a subclass of <code> IOException </code> and therefore need not be
0147: * caught separately, but if you are going to catch it separately, its
0148: * catch block must appear before the more general <code> IOException </code>
0149: * catch block. When you encounter an
0150: * {@link org.apache.commons.net.ftp.FTPConnectionClosedException}
0151: * , you must disconnect the connection with
0152: * {@link #disconnect disconnect() } to properly clean up the
0153: * system resources used by FTPClient. Before disconnecting, you may check the
0154: * last reply code and text with
0155: * {@link org.apache.commons.net.ftp.FTP#getReplyCode getReplyCode },
0156: * {@link org.apache.commons.net.ftp.FTP#getReplyString getReplyString },
0157: * and
0158: * {@link org.apache.commons.net.ftp.FTP#getReplyStrings getReplyStrings}.
0159: * You may avoid server disconnections while the client is idle by
0160: * periodicaly sending NOOP commands to the server.
0161: * <p>
0162: * Rather than list it separately for each method, we mention here that
0163: * every method communicating with the server and throwing an IOException
0164: * can also throw a
0165: * {@link org.apache.commons.net.MalformedServerReplyException}
0166: * , which is a subclass
0167: * of IOException. A MalformedServerReplyException will be thrown when
0168: * the reply received from the server deviates enough from the protocol
0169: * specification that it cannot be interpreted in a useful manner despite
0170: * attempts to be as lenient as possible.
0171: * <p>
0172: * Listing API Examples
0173: * Both paged and unpaged examples of directory listings are available,
0174: * as follows:
0175: * <p>
0176: * Unpaged (whole list) access, using a parser accessible by auto-detect:
0177: * <pre>
0178: * FTPClient f=FTPClient();
0179: * f.connect(server);
0180: * f.login(username, password);
0181: * FTPFile[] files = listFiles(directory);
0182: * </pre>
0183: * <p>
0184: * Paged access, using a parser not accessible by auto-detect. The class
0185: * defined in the first parameter of initateListParsing should be derived
0186: * from org.apache.commons.net.FTPFileEntryParser:
0187: * <pre>
0188: * FTPClient f=FTPClient();
0189: * f.connect(server);
0190: * f.login(username, password);
0191: * FTPListParseEngine engine =
0192: * f.initiateListParsing("com.whatever.YourOwnParser", directory);
0193: *
0194: * while (engine.hasNext()) {
0195: * FTPFile[] files = engine.getNext(25); // "page size" you want
0196: * //do whatever you want with these files, display them, etc.
0197: * //expensive FTPFile objects not created until needed.
0198: * }
0199: * </pre>
0200: * <p>
0201: * Paged access, using a parser accessible by auto-detect:
0202: * <pre>
0203: * FTPClient f=FTPClient();
0204: * f.connect(server);
0205: * f.login(username, password);
0206: * FTPListParseEngine engine = f.initiateListParsing(directory);
0207: *
0208: * while (engine.hasNext()) {
0209: * FTPFile[] files = engine.getNext(25); // "page size" you want
0210: * //do whatever you want with these files, display them, etc.
0211: * //expensive FTPFile objects not created until needed.
0212: * }
0213: * </pre>
0214: * <p>
0215: * For examples of using FTPClient on servers whose directory listings
0216: * <ul>
0217: * <li>use languages other than English</li>
0218: * <li>use date formats other than the American English "standard" <code>MM d yyyy</code></li>
0219: * <li>are in different timezones and you need accurate timestamps for dependency checking
0220: * as in Ant</li>
0221: * </ul>see {@link FTPClientConfig FTPClientConfig}.
0222: * <p>
0223: * NOTE: If you experience problems with unwanted firing of <pre>setSoTimeout()</pre>
0224: * during periods of client inactivity, this can be alleviated by calling <pre>setReaderThread(false)</pre>.
0225: * For more details, see <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=31122">this thread</a>.
0226: * </p>
0227: * <p>
0228: * @author Daniel F. Savarese
0229: * @see FTP
0230: * @see FTPConnectionClosedException
0231: * @see FTPFileEntryParser
0232: * @see FTPFileEntryParserFactory
0233: * @see DefaultFTPFileEntryParserFactory
0234: * @see FTPClientConfig
0235: * @see org.apache.commons.net.MalformedServerReplyException
0236: **/
0237: public class FTPClient extends FTP implements Configurable {
0238: /***
0239: * A constant indicating the FTP session is expecting all transfers
0240: * to occur between the client (local) and server and that the server
0241: * should connect to the client's data port to initiate a data transfer.
0242: * This is the default data connection mode when and FTPClient instance
0243: * is created.
0244: ***/
0245: public static final int ACTIVE_LOCAL_DATA_CONNECTION_MODE = 0;
0246: /***
0247: * A constant indicating the FTP session is expecting all transfers
0248: * to occur between two remote servers and that the server
0249: * the client is connected to should connect to the other server's
0250: * data port to initiate a data transfer.
0251: ***/
0252: public static final int ACTIVE_REMOTE_DATA_CONNECTION_MODE = 1;
0253: /***
0254: * A constant indicating the FTP session is expecting all transfers
0255: * to occur between the client (local) and server and that the server
0256: * is in passive mode, requiring the client to connect to the
0257: * server's data port to initiate a transfer.
0258: ***/
0259: public static final int PASSIVE_LOCAL_DATA_CONNECTION_MODE = 2;
0260: /***
0261: * A constant indicating the FTP session is expecting all transfers
0262: * to occur between two remote servers and that the server
0263: * the client is connected to is in passive mode, requiring the other
0264: * server to connect to the first server's data port to initiate a data
0265: * transfer.
0266: ***/
0267: public static final int PASSIVE_REMOTE_DATA_CONNECTION_MODE = 3;
0268:
0269: private int __dataConnectionMode, __dataTimeout;
0270: private int __passivePort;
0271: private String __passiveHost;
0272: private int __fileType, __fileFormat, __fileStructure,
0273: __fileTransferMode;
0274: private boolean __remoteVerificationEnabled;
0275: private long __restartOffset;
0276: private FTPFileEntryParserFactory __parserFactory;
0277: private int __bufferSize;
0278:
0279: // __systemName is a cached value that should not be referenced directly
0280: // except when assigned in getSystemName and __initDefaults.
0281: private String __systemName;
0282:
0283: // __entryParser is a cached value that should not be referenced directly
0284: // except when assigned in listFiles(String, String) and __initDefaults.
0285: private FTPFileEntryParser __entryParser;
0286:
0287: private FTPClientConfig __configuration;
0288:
0289: /***
0290: * Default FTPClient constructor. Creates a new FTPClient instance
0291: * with the data connection mode set to
0292: * <code> ACTIVE_LOCAL_DATA_CONNECTION_MODE </code>, the file type
0293: * set to <code> FTP.ASCII_FILE_TYPE </code>, the
0294: * file format set to <code> FTP.NON_PRINT_TEXT_FORMAT </code>,
0295: * the file structure set to <code> FTP.FILE_STRUCTURE </code>, and
0296: * the transfer mode set to <code> FTP.STREAM_TRANSFER_MODE </code>.
0297: ***/
0298: public FTPClient() {
0299: __initDefaults();
0300: __dataTimeout = -1;
0301: __remoteVerificationEnabled = true;
0302: __parserFactory = new DefaultFTPFileEntryParserFactory();
0303: __configuration = null;
0304: }
0305:
0306: private void __initDefaults() {
0307: __dataConnectionMode = ACTIVE_LOCAL_DATA_CONNECTION_MODE;
0308: __passiveHost = null;
0309: __passivePort = -1;
0310: __fileType = FTP.ASCII_FILE_TYPE;
0311: __fileStructure = FTP.FILE_STRUCTURE;
0312: __fileFormat = FTP.NON_PRINT_TEXT_FORMAT;
0313: __fileTransferMode = FTP.STREAM_TRANSFER_MODE;
0314: __restartOffset = 0;
0315: __systemName = null;
0316: __entryParser = null;
0317: __bufferSize = Util.DEFAULT_COPY_BUFFER_SIZE;
0318: }
0319:
0320: private String __parsePathname(String reply) {
0321: int begin, end;
0322:
0323: begin = reply.indexOf('"') + 1;
0324: end = reply.indexOf('"', begin);
0325:
0326: return reply.substring(begin, end);
0327: }
0328:
0329: private void __parsePassiveModeReply(String reply)
0330: throws MalformedServerReplyException {
0331: int i, index, lastIndex;
0332: String octet1, octet2;
0333: StringBuffer host;
0334:
0335: reply = reply.substring(reply.indexOf('(') + 1,
0336: reply.indexOf(')')).trim();
0337:
0338: host = new StringBuffer(24);
0339: lastIndex = 0;
0340: index = reply.indexOf(',');
0341: host.append(reply.substring(lastIndex, index));
0342:
0343: for (i = 0; i < 3; i++) {
0344: host.append('.');
0345: lastIndex = index + 1;
0346: index = reply.indexOf(',', lastIndex);
0347: host.append(reply.substring(lastIndex, index));
0348: }
0349:
0350: lastIndex = index + 1;
0351: index = reply.indexOf(',', lastIndex);
0352:
0353: octet1 = reply.substring(lastIndex, index);
0354: octet2 = reply.substring(index + 1);
0355:
0356: // index and lastIndex now used as temporaries
0357: try {
0358: index = Integer.parseInt(octet1);
0359: lastIndex = Integer.parseInt(octet2);
0360: } catch (NumberFormatException e) {
0361: throw new MalformedServerReplyException(
0362: "Could not parse passive host information.\nServer Reply: "
0363: + reply);
0364: }
0365:
0366: index <<= 8;
0367: index |= lastIndex;
0368:
0369: __passiveHost = host.toString();
0370: __passivePort = index;
0371: }
0372:
0373: private boolean __storeFile(int command, String remote,
0374: InputStream local) throws IOException {
0375: OutputStream output;
0376: Socket socket;
0377:
0378: if ((socket = _openDataConnection_(command, remote)) == null)
0379: return false;
0380:
0381: output = new BufferedOutputStream(socket.getOutputStream(),
0382: getBufferSize());
0383: if (__fileType == ASCII_FILE_TYPE)
0384: output = new ToNetASCIIOutputStream(output);
0385: // Treat everything else as binary for now
0386: try {
0387: Util.copyStream(local, output, getBufferSize(),
0388: CopyStreamEvent.UNKNOWN_STREAM_SIZE, null, false);
0389: } catch (IOException e) {
0390: try {
0391: socket.close();
0392: } catch (IOException f) {
0393: }
0394: throw e;
0395: }
0396: output.close();
0397: socket.close();
0398: return completePendingCommand();
0399: }
0400:
0401: private OutputStream __storeFileStream(int command, String remote)
0402: throws IOException {
0403: OutputStream output;
0404: Socket socket;
0405:
0406: if ((socket = _openDataConnection_(command, remote)) == null)
0407: return null;
0408:
0409: output = socket.getOutputStream();
0410: if (__fileType == ASCII_FILE_TYPE) {
0411: // We buffer ascii transfers because the buffering has to
0412: // be interposed between ToNetASCIIOutputSream and the underlying
0413: // socket output stream. We don't buffer binary transfers
0414: // because we don't want to impose a buffering policy on the
0415: // programmer if possible. Programmers can decide on their
0416: // own if they want to wrap the SocketOutputStream we return
0417: // for file types other than ASCII.
0418: output = new BufferedOutputStream(output, getBufferSize());
0419: output = new ToNetASCIIOutputStream(output);
0420:
0421: }
0422: return new org.apache.commons.net.io.SocketOutputStream(socket,
0423: output);
0424: }
0425:
0426: /**
0427: * Establishes a data connection with the FTP server, returning
0428: * a Socket for the connection if successful. If a restart
0429: * offset has been set with {@link #setRestartOffset(long)},
0430: * a REST command is issued to the server with the offset as
0431: * an argument before establishing the data connection. Active
0432: * mode connections also cause a local PORT command to be issued.
0433: * <p>
0434: * @param command The text representation of the FTP command to send.
0435: * @param arg The arguments to the FTP command. If this parameter is
0436: * set to null, then the command is sent with no argument.
0437: * @return A Socket corresponding to the established data connection.
0438: * Null is returned if an FTP protocol error is reported at
0439: * any point during the establishment and initialization of
0440: * the connection.
0441: * @exception IOException If an I/O error occurs while either sending a
0442: * command to the server or receiving a reply from the server.
0443: */
0444: protected Socket _openDataConnection_(int command, String arg)
0445: throws IOException {
0446: Socket socket;
0447:
0448: if (__dataConnectionMode != ACTIVE_LOCAL_DATA_CONNECTION_MODE
0449: && __dataConnectionMode != PASSIVE_LOCAL_DATA_CONNECTION_MODE)
0450: return null;
0451:
0452: if (__dataConnectionMode == ACTIVE_LOCAL_DATA_CONNECTION_MODE) {
0453: ServerSocket server;
0454: server = _socketFactory_.createServerSocket(0, 1,
0455: getLocalAddress());
0456:
0457: if (!FTPReply.isPositiveCompletion(port(getLocalAddress(),
0458: server.getLocalPort()))) {
0459: server.close();
0460: return null;
0461: }
0462:
0463: if ((__restartOffset > 0) && !restart(__restartOffset)) {
0464: server.close();
0465: return null;
0466: }
0467:
0468: if (!FTPReply.isPositivePreliminary(sendCommand(command,
0469: arg))) {
0470: server.close();
0471: return null;
0472: }
0473:
0474: // For now, let's just use the data timeout value for waiting for
0475: // the data connection. It may be desirable to let this be a
0476: // separately configurable value. In any case, we really want
0477: // to allow preventing the accept from blocking indefinitely.
0478: if (__dataTimeout >= 0)
0479: server.setSoTimeout(__dataTimeout);
0480: socket = server.accept();
0481: server.close();
0482: } else { // We must be in PASSIVE_LOCAL_DATA_CONNECTION_MODE
0483:
0484: if (pasv() != FTPReply.ENTERING_PASSIVE_MODE)
0485: return null;
0486:
0487: __parsePassiveModeReply((String) _replyLines.elementAt(0));
0488:
0489: socket = _socketFactory_.createSocket(__passiveHost,
0490: __passivePort);
0491: if ((__restartOffset > 0) && !restart(__restartOffset)) {
0492: socket.close();
0493: return null;
0494: }
0495:
0496: if (!FTPReply.isPositivePreliminary(sendCommand(command,
0497: arg))) {
0498: socket.close();
0499: return null;
0500: }
0501: }
0502:
0503: if (__remoteVerificationEnabled && !verifyRemote(socket)) {
0504: InetAddress host1, host2;
0505:
0506: host1 = socket.getInetAddress();
0507: host2 = getRemoteAddress();
0508:
0509: socket.close();
0510:
0511: throw new IOException("Host attempting data connection "
0512: + host1.getHostAddress()
0513: + " is not same as server "
0514: + host2.getHostAddress());
0515: }
0516:
0517: if (__dataTimeout >= 0)
0518: socket.setSoTimeout(__dataTimeout);
0519:
0520: return socket;
0521: }
0522:
0523: protected void _connectAction_() throws IOException {
0524: super ._connectAction_();
0525: __initDefaults();
0526: }
0527:
0528: /***
0529: * Sets the timeout in milliseconds to use when reading from the
0530: * data connection. This timeout will be set immediately after
0531: * opening the data connection.
0532: * <p>
0533: * @param timeout The default timeout in milliseconds that is used when
0534: * opening a data connection socket.
0535: ***/
0536: public void setDataTimeout(int timeout) {
0537: __dataTimeout = timeout;
0538: }
0539:
0540: /**
0541: * set the factory used for parser creation to the supplied factory object.
0542: *
0543: * @param parserFactory
0544: * factory object used to create FTPFileEntryParsers
0545: *
0546: * @see org.apache.commons.net.ftp.parser.FTPFileEntryParserFactory
0547: * @see org.apache.commons.net.ftp.parser.DefaultFTPFileEntryParserFactory
0548: */
0549: public void setParserFactory(FTPFileEntryParserFactory parserFactory) {
0550: __parserFactory = parserFactory;
0551: }
0552:
0553: /***
0554: * Closes the connection to the FTP server and restores
0555: * connection parameters to the default values.
0556: * <p>
0557: * @exception IOException If an error occurs while disconnecting.
0558: ***/
0559: public void disconnect() throws IOException {
0560: super .disconnect();
0561: __initDefaults();
0562: }
0563:
0564: /***
0565: * Enable or disable verification that the remote host taking part
0566: * of a data connection is the same as the host to which the control
0567: * connection is attached. The default is for verification to be
0568: * enabled. You may set this value at any time, whether the
0569: * FTPClient is currently connected or not.
0570: * <p>
0571: * @param enable True to enable verification, false to disable verification.
0572: ***/
0573: public void setRemoteVerificationEnabled(boolean enable) {
0574: __remoteVerificationEnabled = enable;
0575: }
0576:
0577: /***
0578: * Return whether or not verification of the remote host participating
0579: * in data connections is enabled. The default behavior is for
0580: * verification to be enabled.
0581: * <p>
0582: * @return True if verification is enabled, false if not.
0583: ***/
0584: public boolean isRemoteVerificationEnabled() {
0585: return __remoteVerificationEnabled;
0586: }
0587:
0588: /***
0589: * Login to the FTP server using the provided username and password.
0590: * <p>
0591: * @param username The username to login under.
0592: * @param password The password to use.
0593: * @return True if successfully completed, false if not.
0594: * @exception FTPConnectionClosedException
0595: * If the FTP server prematurely closes the connection as a result
0596: * of the client being idle or some other reason causing the server
0597: * to send FTP reply code 421. This exception may be caught either
0598: * as an IOException or independently as itself.
0599: * @exception IOException If an I/O error occurs while either sending a
0600: * command to the server or receiving a reply from the server.
0601: ***/
0602: public boolean login(String username, String password)
0603: throws IOException {
0604: user(username);
0605:
0606: if (FTPReply.isPositiveCompletion(_replyCode))
0607: return true;
0608:
0609: // If we get here, we either have an error code, or an intermmediate
0610: // reply requesting password.
0611: if (!FTPReply.isPositiveIntermediate(_replyCode))
0612: return false;
0613:
0614: return FTPReply.isPositiveCompletion(pass(password));
0615: }
0616:
0617: /***
0618: * Login to the FTP server using the provided username, password,
0619: * and account. If no account is required by the server, only
0620: * the username and password, the account information is not used.
0621: * <p>
0622: * @param username The username to login under.
0623: * @param password The password to use.
0624: * @param account The account to use.
0625: * @return True if successfully completed, false if not.
0626: * @exception FTPConnectionClosedException
0627: * If the FTP server prematurely closes the connection as a result
0628: * of the client being idle or some other reason causing the server
0629: * to send FTP reply code 421. This exception may be caught either
0630: * as an IOException or independently as itself.
0631: * @exception IOException If an I/O error occurs while either sending a
0632: * command to the server or receiving a reply from the server.
0633: ***/
0634: public boolean login(String username, String password,
0635: String account) throws IOException {
0636: user(username);
0637:
0638: if (FTPReply.isPositiveCompletion(_replyCode))
0639: return true;
0640:
0641: // If we get here, we either have an error code, or an intermmediate
0642: // reply requesting password.
0643: if (!FTPReply.isPositiveIntermediate(_replyCode))
0644: return false;
0645:
0646: pass(password);
0647:
0648: if (FTPReply.isPositiveCompletion(_replyCode))
0649: return true;
0650:
0651: if (!FTPReply.isPositiveIntermediate(_replyCode))
0652: return false;
0653:
0654: return FTPReply.isPositiveCompletion(acct(account));
0655: }
0656:
0657: /***
0658: * Logout of the FTP server by sending the QUIT command.
0659: * <p>
0660: * @return True if successfully completed, false if not.
0661: * @exception FTPConnectionClosedException
0662: * If the FTP server prematurely closes the connection as a result
0663: * of the client being idle or some other reason causing the server
0664: * to send FTP reply code 421. This exception may be caught either
0665: * as an IOException or independently as itself.
0666: * @exception IOException If an I/O error occurs while either sending a
0667: * command to the server or receiving a reply from the server.
0668: ***/
0669: public boolean logout() throws IOException {
0670: return FTPReply.isPositiveCompletion(quit());
0671: }
0672:
0673: /***
0674: * Change the current working directory of the FTP session.
0675: * <p>
0676: * @param pathname The new current working directory.
0677: * @return True if successfully completed, false if not.
0678: * @exception FTPConnectionClosedException
0679: * If the FTP server prematurely closes the connection as a result
0680: * of the client being idle or some other reason causing the server
0681: * to send FTP reply code 421. This exception may be caught either
0682: * as an IOException or independently as itself.
0683: * @exception IOException If an I/O error occurs while either sending a
0684: * command to the server or receiving a reply from the server.
0685: ***/
0686: public boolean changeWorkingDirectory(String pathname)
0687: throws IOException {
0688: return FTPReply.isPositiveCompletion(cwd(pathname));
0689: }
0690:
0691: /***
0692: * Change to the parent directory of the current working directory.
0693: * <p>
0694: * @return True if successfully completed, false if not.
0695: * @exception FTPConnectionClosedException
0696: * If the FTP server prematurely closes the connection as a result
0697: * of the client being idle or some other reason causing the server
0698: * to send FTP reply code 421. This exception may be caught either
0699: * as an IOException or independently as itself.
0700: * @exception IOException If an I/O error occurs while either sending a
0701: * command to the server or receiving a reply from the server.
0702: ***/
0703: public boolean changeToParentDirectory() throws IOException {
0704: return FTPReply.isPositiveCompletion(cdup());
0705: }
0706:
0707: /***
0708: * Issue the FTP SMNT command.
0709: * <p>
0710: * @param pathname The pathname to mount.
0711: * @return True if successfully completed, false if not.
0712: * @exception FTPConnectionClosedException
0713: * If the FTP server prematurely closes the connection as a result
0714: * of the client being idle or some other reason causing the server
0715: * to send FTP reply code 421. This exception may be caught either
0716: * as an IOException or independently as itself.
0717: * @exception IOException If an I/O error occurs while either sending a
0718: * command to the server or receiving a reply from the server.
0719: ***/
0720: public boolean structureMount(String pathname) throws IOException {
0721: return FTPReply.isPositiveCompletion(smnt(pathname));
0722: }
0723:
0724: /***
0725: * Reinitialize the FTP session. Not all FTP servers support this
0726: * command, which issues the FTP REIN command.
0727: * <p>
0728: * @return True if successfully completed, false if not.
0729: * @exception FTPConnectionClosedException
0730: * If the FTP server prematurely closes the connection as a result
0731: * of the client being idle or some other reason causing the server
0732: * to send FTP reply code 421. This exception may be caught either
0733: * as an IOException or independently as itself.
0734: * @exception IOException If an I/O error occurs while either sending a
0735: * command to the server or receiving a reply from the server.
0736: ***/
0737: boolean reinitialize() throws IOException {
0738: rein();
0739:
0740: if (FTPReply.isPositiveCompletion(_replyCode)
0741: || (FTPReply.isPositivePreliminary(_replyCode) && FTPReply
0742: .isPositiveCompletion(getReply()))) {
0743:
0744: __initDefaults();
0745:
0746: return true;
0747: }
0748:
0749: return false;
0750: }
0751:
0752: /***
0753: * Set the current data connection mode to
0754: * <code>ACTIVE_LOCAL_DATA_CONNECTION_MODE</code>. No communication
0755: * with the FTP server is conducted, but this causes all future data
0756: * transfers to require the FTP server to connect to the client's
0757: * data port. Additionally, to accommodate differences between socket
0758: * implementations on different platforms, this method causes the
0759: * client to issue a PORT command before every data transfer.
0760: ***/
0761: public void enterLocalActiveMode() {
0762: __dataConnectionMode = ACTIVE_LOCAL_DATA_CONNECTION_MODE;
0763: __passiveHost = null;
0764: __passivePort = -1;
0765: }
0766:
0767: /***
0768: * Set the current data connection mode to
0769: * <code> PASSIVE_LOCAL_DATA_CONNECTION_MODE </code>. Use this
0770: * method only for data transfers between the client and server.
0771: * This method causes a PASV command to be issued to the server
0772: * before the opening of every data connection, telling the server to
0773: * open a data port to which the client will connect to conduct
0774: * data transfers. The FTPClient will stay in
0775: * <code> PASSIVE_LOCAL_DATA_CONNECTION_MODE </code> until the
0776: * mode is changed by calling some other method such as
0777: * {@link #enterLocalActiveMode enterLocalActiveMode() }
0778: ***/
0779: public void enterLocalPassiveMode() {
0780: __dataConnectionMode = PASSIVE_LOCAL_DATA_CONNECTION_MODE;
0781: // These will be set when just before a data connection is opened
0782: // in _openDataConnection_()
0783: __passiveHost = null;
0784: __passivePort = -1;
0785: }
0786:
0787: /***
0788: * Set the current data connection mode to
0789: * <code> ACTIVE_REMOTE_DATA_CONNECTION </code>. Use this method only
0790: * for server to server data transfers. This method issues a PORT
0791: * command to the server, indicating the other server and port to which
0792: * it should connect for data transfers. You must call this method
0793: * before EVERY server to server transfer attempt. The FTPClient will
0794: * NOT automatically continue to issue PORT commands. You also
0795: * must remember to call
0796: * {@link #enterLocalActiveMode enterLocalActiveMode() } if you
0797: * wish to return to the normal data connection mode.
0798: * <p>
0799: * @param host The passive mode server accepting connections for data
0800: * transfers.
0801: * @param port The passive mode server's data port.
0802: * @return True if successfully completed, false if not.
0803: * @exception FTPConnectionClosedException
0804: * If the FTP server prematurely closes the connection as a result
0805: * of the client being idle or some other reason causing the server
0806: * to send FTP reply code 421. This exception may be caught either
0807: * as an IOException or independently as itself.
0808: * @exception IOException If an I/O error occurs while either sending a
0809: * command to the server or receiving a reply from the server.
0810: ***/
0811: public boolean enterRemoteActiveMode(InetAddress host, int port)
0812: throws IOException {
0813: if (FTPReply.isPositiveCompletion(port(host, port))) {
0814: __dataConnectionMode = ACTIVE_REMOTE_DATA_CONNECTION_MODE;
0815: __passiveHost = null;
0816: __passivePort = -1;
0817: return true;
0818: }
0819: return false;
0820: }
0821:
0822: /***
0823: * Set the current data connection mode to
0824: * <code> PASSIVE_REMOTE_DATA_CONNECTION_MODE </code>. Use this
0825: * method only for server to server data transfers.
0826: * This method issues a PASV command to the server, telling it to
0827: * open a data port to which the active server will connect to conduct
0828: * data transfers. You must call this method
0829: * before EVERY server to server transfer attempt. The FTPClient will
0830: * NOT automatically continue to issue PASV commands. You also
0831: * must remember to call
0832: * {@link #enterLocalActiveMode enterLocalActiveMode() } if you
0833: * wish to return to the normal data connection mode.
0834: * <p>
0835: * @return True if successfully completed, false if not.
0836: * @exception FTPConnectionClosedException
0837: * If the FTP server prematurely closes the connection as a result
0838: * of the client being idle or some other reason causing the server
0839: * to send FTP reply code 421. This exception may be caught either
0840: * as an IOException or independently as itself.
0841: * @exception IOException If an I/O error occurs while either sending a
0842: * command to the server or receiving a reply from the server.
0843: ***/
0844: public boolean enterRemotePassiveMode() throws IOException {
0845: if (pasv() != FTPReply.ENTERING_PASSIVE_MODE)
0846: return false;
0847:
0848: __dataConnectionMode = PASSIVE_REMOTE_DATA_CONNECTION_MODE;
0849: __parsePassiveModeReply((String) _replyLines.elementAt(0));
0850:
0851: return true;
0852: }
0853:
0854: /***
0855: * Returns the hostname or IP address (in the form of a string) returned
0856: * by the server when entering passive mode. If not in passive mode,
0857: * returns null. This method only returns a valid value AFTER a
0858: * data connection has been opened after a call to
0859: * {@link #enterLocalPassiveMode enterLocalPassiveMode()}.
0860: * This is because FTPClient sends a PASV command to the server only
0861: * just before opening a data connection, and not when you call
0862: * {@link #enterLocalPassiveMode enterLocalPassiveMode()}.
0863: * <p>
0864: * @return The passive host name if in passive mode, otherwise null.
0865: ***/
0866: public String getPassiveHost() {
0867: return __passiveHost;
0868: }
0869:
0870: /***
0871: * If in passive mode, returns the data port of the passive host.
0872: * This method only returns a valid value AFTER a
0873: * data connection has been opened after a call to
0874: * {@link #enterLocalPassiveMode enterLocalPassiveMode()}.
0875: * This is because FTPClient sends a PASV command to the server only
0876: * just before opening a data connection, and not when you call
0877: * {@link #enterLocalPassiveMode enterLocalPassiveMode()}.
0878: * <p>
0879: * @return The data port of the passive server. If not in passive
0880: * mode, undefined.
0881: ***/
0882: public int getPassivePort() {
0883: return __passivePort;
0884: }
0885:
0886: /***
0887: * Returns the current data connection mode (one of the
0888: * <code> _DATA_CONNECTION_MODE </code> constants.
0889: * <p>
0890: * @return The current data connection mode (one of the
0891: * <code> _DATA_CONNECTION_MODE </code> constants.
0892: ***/
0893: public int getDataConnectionMode() {
0894: return __dataConnectionMode;
0895: }
0896:
0897: /***
0898: * Sets the file type to be transferred. This should be one of
0899: * <code> FTP.ASCII_FILE_TYPE </code>, <code> FTP.IMAGE_FILE_TYPE </code>,
0900: * etc. The file type only needs to be set when you want to change the
0901: * type. After changing it, the new type stays in effect until you change
0902: * it again. The default file type is <code> FTP.ASCII_FILE_TYPE </code>
0903: * if this method is never called.
0904: * <p>
0905: * @param fileType The <code> _FILE_TYPE </code> constant indcating the
0906: * type of file.
0907: * @return True if successfully completed, false if not.
0908: * @exception FTPConnectionClosedException
0909: * If the FTP server prematurely closes the connection as a result
0910: * of the client being idle or some other reason causing the server
0911: * to send FTP reply code 421. This exception may be caught either
0912: * as an IOException or independently as itself.
0913: * @exception IOException If an I/O error occurs while either sending a
0914: * command to the server or receiving a reply from the server.
0915: ***/
0916: public boolean setFileType(int fileType) throws IOException {
0917: if (FTPReply.isPositiveCompletion(type(fileType))) {
0918: __fileType = fileType;
0919: __fileFormat = FTP.NON_PRINT_TEXT_FORMAT;
0920: return true;
0921: }
0922: return false;
0923: }
0924:
0925: /***
0926: * Sets the file type to be transferred and the format. The type should be
0927: * one of <code> FTP.ASCII_FILE_TYPE </code>,
0928: * <code> FTP.IMAGE_FILE_TYPE </code>, etc. The file type only needs to
0929: * be set when you want to change the type. After changing it, the new
0930: * type stays in effect until you change it again. The default file type
0931: * is <code> FTP.ASCII_FILE_TYPE </code> if this method is never called.
0932: * The format should be one of the FTP class <code> TEXT_FORMAT </code>
0933: * constants, or if the type is <code> FTP.LOCAL_FILE_TYPE </code>, the
0934: * format should be the byte size for that type. The default format
0935: * is <code> FTP.NON_PRINT_TEXT_FORMAT </code> if this method is never
0936: * called.
0937: * <p>
0938: * @param fileType The <code> _FILE_TYPE </code> constant indcating the
0939: * type of file.
0940: * @param formatOrByteSize The format of the file (one of the
0941: * <code>_FORMAT</code> constants. In the case of
0942: * <code>LOCAL_FILE_TYPE</code>, the byte size.
0943: * <p>
0944: * @return True if successfully completed, false if not.
0945: * @exception FTPConnectionClosedException
0946: * If the FTP server prematurely closes the connection as a result
0947: * of the client being idle or some other reason causing the server
0948: * to send FTP reply code 421. This exception may be caught either
0949: * as an IOException or independently as itself.
0950: * @exception IOException If an I/O error occurs while either sending a
0951: * command to the server or receiving a reply from the server.
0952: ***/
0953: public boolean setFileType(int fileType, int formatOrByteSize)
0954: throws IOException {
0955: if (FTPReply.isPositiveCompletion(type(fileType,
0956: formatOrByteSize))) {
0957: __fileType = fileType;
0958: __fileFormat = formatOrByteSize;
0959: return true;
0960: }
0961: return false;
0962: }
0963:
0964: /***
0965: * Sets the file structure. The default structure is
0966: * <code> FTP.FILE_STRUCTURE </code> if this method is never called.
0967: * <p>
0968: * @param structure The structure of the file (one of the FTP class
0969: * <code>_STRUCTURE</code> constants).
0970: * @return True if successfully completed, false if not.
0971: * @exception FTPConnectionClosedException
0972: * If the FTP server prematurely closes the connection as a result
0973: * of the client being idle or some other reason causing the server
0974: * to send FTP reply code 421. This exception may be caught either
0975: * as an IOException or independently as itself.
0976: * @exception IOException If an I/O error occurs while either sending a
0977: * command to the server or receiving a reply from the server.
0978: ***/
0979: public boolean setFileStructure(int structure) throws IOException {
0980: if (FTPReply.isPositiveCompletion(stru(structure))) {
0981: __fileStructure = structure;
0982: return true;
0983: }
0984: return false;
0985: }
0986:
0987: /***
0988: * Sets the transfer mode. The default transfer mode
0989: * <code> FTP.STREAM_TRANSFER_MODE </code> if this method is never called.
0990: * <p>
0991: * @param mode The new transfer mode to use (one of the FTP class
0992: * <code>_TRANSFER_MODE</code> constants).
0993: * @return True if successfully completed, false if not.
0994: * @exception FTPConnectionClosedException
0995: * If the FTP server prematurely closes the connection as a result
0996: * of the client being idle or some other reason causing the server
0997: * to send FTP reply code 421. This exception may be caught either
0998: * as an IOException or independently as itself.
0999: * @exception IOException If an I/O error occurs while either sending a
1000: * command to the server or receiving a reply from the server.
1001: ***/
1002: public boolean setFileTransferMode(int mode) throws IOException {
1003: if (FTPReply.isPositiveCompletion(mode(mode))) {
1004: __fileTransferMode = mode;
1005: return true;
1006: }
1007: return false;
1008: }
1009:
1010: /***
1011: * Initiate a server to server file transfer. This method tells the
1012: * server to which the client is connected to retrieve a given file from
1013: * the other server.
1014: * <p>
1015: * @param filename The name of the file to retrieve.
1016: * @return True if successfully completed, false if not.
1017: * @exception FTPConnectionClosedException
1018: * If the FTP server prematurely closes the connection as a result
1019: * of the client being idle or some other reason causing the server
1020: * to send FTP reply code 421. This exception may be caught either
1021: * as an IOException or independently as itself.
1022: * @exception IOException If an I/O error occurs while either sending a
1023: * command to the server or receiving a reply from the server.
1024: ***/
1025: public boolean remoteRetrieve(String filename) throws IOException {
1026: if (__dataConnectionMode == ACTIVE_REMOTE_DATA_CONNECTION_MODE
1027: || __dataConnectionMode == PASSIVE_REMOTE_DATA_CONNECTION_MODE)
1028: return FTPReply.isPositivePreliminary(retr(filename));
1029: return false;
1030: }
1031:
1032: /***
1033: * Initiate a server to server file transfer. This method tells the
1034: * server to which the client is connected to store a file on
1035: * the other server using the given filename. The other server must
1036: * have had a <code> remoteRetrieve </code> issued to it by another
1037: * FTPClient.
1038: * <p>
1039: * @param filename The name to call the file that is to be stored.
1040: * @return True if successfully completed, false if not.
1041: * @exception FTPConnectionClosedException
1042: * If the FTP server prematurely closes the connection as a result
1043: * of the client being idle or some other reason causing the server
1044: * to send FTP reply code 421. This exception may be caught either
1045: * as an IOException or independently as itself.
1046: * @exception IOException If an I/O error occurs while either sending a
1047: * command to the server or receiving a reply from the server.
1048: ***/
1049: public boolean remoteStore(String filename) throws IOException {
1050: if (__dataConnectionMode == ACTIVE_REMOTE_DATA_CONNECTION_MODE
1051: || __dataConnectionMode == PASSIVE_REMOTE_DATA_CONNECTION_MODE)
1052: return FTPReply.isPositivePreliminary(stor(filename));
1053: return false;
1054: }
1055:
1056: /***
1057: * Initiate a server to server file transfer. This method tells the
1058: * server to which the client is connected to store a file on
1059: * the other server using a unique filename based on the given filename.
1060: * The other server must have had a <code> remoteRetrieve </code> issued
1061: * to it by another FTPClient.
1062: * <p>
1063: * @param filename The name on which to base the filename of the file
1064: * that is to be stored.
1065: * @return True if successfully completed, false if not.
1066: * @exception FTPConnectionClosedException
1067: * If the FTP server prematurely closes the connection as a result
1068: * of the client being idle or some other reason causing the server
1069: * to send FTP reply code 421. This exception may be caught either
1070: * as an IOException or independently as itself.
1071: * @exception IOException If an I/O error occurs while either sending a
1072: * command to the server or receiving a reply from the server.
1073: ***/
1074: public boolean remoteStoreUnique(String filename)
1075: throws IOException {
1076: if (__dataConnectionMode == ACTIVE_REMOTE_DATA_CONNECTION_MODE
1077: || __dataConnectionMode == PASSIVE_REMOTE_DATA_CONNECTION_MODE)
1078: return FTPReply.isPositivePreliminary(stou(filename));
1079: return false;
1080: }
1081:
1082: /***
1083: * Initiate a server to server file transfer. This method tells the
1084: * server to which the client is connected to store a file on
1085: * the other server using a unique filename.
1086: * The other server must have had a <code> remoteRetrieve </code> issued
1087: * to it by another FTPClient. Many FTP servers require that a base
1088: * filename be given from which the unique filename can be derived. For
1089: * those servers use the other version of <code> remoteStoreUnique</code>
1090: * <p>
1091: * @return True if successfully completed, false if not.
1092: * @exception FTPConnectionClosedException
1093: * If the FTP server prematurely closes the connection as a result
1094: * of the client being idle or some other reason causing the server
1095: * to send FTP reply code 421. This exception may be caught either
1096: * as an IOException or independently as itself.
1097: * @exception IOException If an I/O error occurs while either sending a
1098: * command to the server or receiving a reply from the server.
1099: ***/
1100: public boolean remoteStoreUnique() throws IOException {
1101: if (__dataConnectionMode == ACTIVE_REMOTE_DATA_CONNECTION_MODE
1102: || __dataConnectionMode == PASSIVE_REMOTE_DATA_CONNECTION_MODE)
1103: return FTPReply.isPositivePreliminary(stou());
1104: return false;
1105: }
1106:
1107: // For server to server transfers
1108: /***
1109: * Initiate a server to server file transfer. This method tells the
1110: * server to which the client is connected to append to a given file on
1111: * the other server. The other server must have had a
1112: * <code> remoteRetrieve </code> issued to it by another FTPClient.
1113: * <p>
1114: * @param filename The name of the file to be appended to, or if the
1115: * file does not exist, the name to call the file being stored.
1116: * <p>
1117: * @return True if successfully completed, false if not.
1118: * @exception FTPConnectionClosedException
1119: * If the FTP server prematurely closes the connection as a result
1120: * of the client being idle or some other reason causing the server
1121: * to send FTP reply code 421. This exception may be caught either
1122: * as an IOException or independently as itself.
1123: * @exception IOException If an I/O error occurs while either sending a
1124: * command to the server or receiving a reply from the server.
1125: ***/
1126: public boolean remoteAppend(String filename) throws IOException {
1127: if (__dataConnectionMode == ACTIVE_REMOTE_DATA_CONNECTION_MODE
1128: || __dataConnectionMode == PASSIVE_REMOTE_DATA_CONNECTION_MODE)
1129: return FTPReply.isPositivePreliminary(stor(filename));
1130: return false;
1131: }
1132:
1133: /***
1134: * There are a few FTPClient methods that do not complete the
1135: * entire sequence of FTP commands to complete a transaction. These
1136: * commands require some action by the programmer after the reception
1137: * of a positive intermediate command. After the programmer's code
1138: * completes its actions, it must call this method to receive
1139: * the completion reply from the server and verify the success of the
1140: * entire transaction.
1141: * <p>
1142: * For example,
1143: * <pre>
1144: * InputStream input;
1145: * OutputStream output;
1146: * input = new FileInputStream("foobaz.txt");
1147: * output = ftp.storeFileStream("foobar.txt")
1148: * if(!FTPReply.isPositiveIntermediate(ftp.getReplyCode())) {
1149: * input.close();
1150: * output.close();
1151: * ftp.logout();
1152: * ftp.disconnect();
1153: * System.err.println("File transfer failed.");
1154: * System.exit(1);
1155: * }
1156: * Util.copyStream(input, output);
1157: * input.close();
1158: * output.close();
1159: * // Must call completePendingCommand() to finish command.
1160: * if(!ftp.completePendingCommand()) {
1161: * ftp.logout();
1162: * ftp.disconnect();
1163: * System.err.println("File transfer failed.");
1164: * System.exit(1);
1165: * }
1166: * </pre>
1167: * <p>
1168: * @return True if successfully completed, false if not.
1169: * @exception FTPConnectionClosedException
1170: * If the FTP server prematurely closes the connection as a result
1171: * of the client being idle or some other reason causing the server
1172: * to send FTP reply code 421. This exception may be caught either
1173: * as an IOException or independently as itself.
1174: * @exception IOException If an I/O error occurs while either sending a
1175: * command to the server or receiving a reply from the server.
1176: ***/
1177: public boolean completePendingCommand() throws IOException {
1178: return FTPReply.isPositiveCompletion(getReply());
1179: }
1180:
1181: /***
1182: * Retrieves a named file from the server and writes it to the given
1183: * OutputStream. This method does NOT close the given OutputStream.
1184: * If the current file type is ASCII, line separators in the file are
1185: * converted to the local representation.
1186: * <p>
1187: * @param remote The name of the remote file.
1188: * @param local The local OutputStream to which to write the file.
1189: * @return True if successfully completed, false if not.
1190: * @exception FTPConnectionClosedException
1191: * If the FTP server prematurely closes the connection as a result
1192: * of the client being idle or some other reason causing the server
1193: * to send FTP reply code 421. This exception may be caught either
1194: * as an IOException or independently as itself.
1195: * @exception CopyStreamException If an I/O error occurs while actually
1196: * transferring the file. The CopyStreamException allows you to
1197: * determine the number of bytes transferred and the IOException
1198: * causing the error. This exception may be caught either
1199: * as an IOException or independently as itself.
1200: * @exception IOException If an I/O error occurs while either sending a
1201: * command to the server or receiving a reply from the server.
1202: ***/
1203: public boolean retrieveFile(String remote, OutputStream local)
1204: throws IOException {
1205: InputStream input;
1206: Socket socket;
1207:
1208: if ((socket = _openDataConnection_(FTPCommand.RETR, remote)) == null)
1209: return false;
1210:
1211: input = new BufferedInputStream(socket.getInputStream(),
1212: getBufferSize());
1213: if (__fileType == ASCII_FILE_TYPE)
1214: input = new FromNetASCIIInputStream(input);
1215: // Treat everything else as binary for now
1216: try {
1217: Util.copyStream(input, local, getBufferSize(),
1218: CopyStreamEvent.UNKNOWN_STREAM_SIZE, null, false);
1219: } catch (IOException e) {
1220: try {
1221: socket.close();
1222: } catch (IOException f) {
1223: }
1224: throw e;
1225: }
1226: socket.close();
1227: return completePendingCommand();
1228: }
1229:
1230: /***
1231: * Returns an InputStream from which a named file from the server
1232: * can be read. If the current file type is ASCII, the returned
1233: * InputStream will convert line separators in the file to
1234: * the local representation. You must close the InputStream when you
1235: * finish reading from it. The InputStream itself will take care of
1236: * closing the parent data connection socket upon being closed. To
1237: * finalize the file transfer you must call
1238: * {@link #completePendingCommand completePendingCommand } and
1239: * check its return value to verify success.
1240: * <p>
1241: * @param remote The name of the remote file.
1242: * @return An InputStream from which the remote file can be read. If
1243: * the data connection cannot be opened (e.g., the file does not
1244: * exist), null is returned (in which case you may check the reply
1245: * code to determine the exact reason for failure).
1246: * @exception FTPConnectionClosedException
1247: * If the FTP server prematurely closes the connection as a result
1248: * of the client being idle or some other reason causing the server
1249: * to send FTP reply code 421. This exception may be caught either
1250: * as an IOException or independently as itself.
1251: * @exception IOException If an I/O error occurs while either sending a
1252: * command to the server or receiving a reply from the server.
1253: ***/
1254: public InputStream retrieveFileStream(String remote)
1255: throws IOException {
1256: InputStream input;
1257: Socket socket;
1258:
1259: if ((socket = _openDataConnection_(FTPCommand.RETR, remote)) == null)
1260: return null;
1261:
1262: input = socket.getInputStream();
1263: if (__fileType == ASCII_FILE_TYPE) {
1264: // We buffer ascii transfers because the buffering has to
1265: // be interposed between FromNetASCIIOutputSream and the underlying
1266: // socket input stream. We don't buffer binary transfers
1267: // because we don't want to impose a buffering policy on the
1268: // programmer if possible. Programmers can decide on their
1269: // own if they want to wrap the SocketInputStream we return
1270: // for file types other than ASCII.
1271: input = new BufferedInputStream(input, getBufferSize());
1272: input = new FromNetASCIIInputStream(input);
1273: }
1274: return new org.apache.commons.net.io.SocketInputStream(socket,
1275: input);
1276: }
1277:
1278: /***
1279: * Stores a file on the server using the given name and taking input
1280: * from the given InputStream. This method does NOT close the given
1281: * InputStream. If the current file type is ASCII, line separators in
1282: * the file are transparently converted to the NETASCII format (i.e.,
1283: * you should not attempt to create a special InputStream to do this).
1284: * <p>
1285: * @param remote The name to give the remote file.
1286: * @param local The local InputStream from which to read the file.
1287: * @return True if successfully completed, false if not.
1288: * @exception FTPConnectionClosedException
1289: * If the FTP server prematurely closes the connection as a result
1290: * of the client being idle or some other reason causing the server
1291: * to send FTP reply code 421. This exception may be caught either
1292: * as an IOException or independently as itself.
1293: * @exception CopyStreamException If an I/O error occurs while actually
1294: * transferring the file. The CopyStreamException allows you to
1295: * determine the number of bytes transferred and the IOException
1296: * causing the error. This exception may be caught either
1297: * as an IOException or independently as itself.
1298: * @exception IOException If an I/O error occurs while either sending a
1299: * command to the server or receiving a reply from the server.
1300: ***/
1301: public boolean storeFile(String remote, InputStream local)
1302: throws IOException {
1303: return __storeFile(FTPCommand.STOR, remote, local);
1304: }
1305:
1306: /***
1307: * Returns an OutputStream through which data can be written to store
1308: * a file on the server using the given name. If the current file type
1309: * is ASCII, the returned OutputStream will convert line separators in
1310: * the file to the NETASCII format (i.e., you should not attempt to
1311: * create a special OutputStream to do this). You must close the
1312: * OutputStream when you finish writing to it. The OutputStream itself
1313: * will take care of closing the parent data connection socket upon being
1314: * closed. To finalize the file transfer you must call
1315: * {@link #completePendingCommand completePendingCommand } and
1316: * check its return value to verify success.
1317: * <p>
1318: * @param remote The name to give the remote file.
1319: * @return An OutputStream through which the remote file can be written. If
1320: * the data connection cannot be opened (e.g., the file does not
1321: * exist), null is returned (in which case you may check the reply
1322: * code to determine the exact reason for failure).
1323: * @exception FTPConnectionClosedException
1324: * If the FTP server prematurely closes the connection as a result
1325: * of the client being idle or some other reason causing the server
1326: * to send FTP reply code 421. This exception may be caught either
1327: * as an IOException or independently as itself.
1328: * @exception IOException If an I/O error occurs while either sending a
1329: * command to the server or receiving a reply from the server.
1330: ***/
1331: public OutputStream storeFileStream(String remote)
1332: throws IOException {
1333: return __storeFileStream(FTPCommand.STOR, remote);
1334: }
1335:
1336: /***
1337: * Appends to a file on the server with the given name, taking input
1338: * from the given InputStream. This method does NOT close the given
1339: * InputStream. If the current file type is ASCII, line separators in
1340: * the file are transparently converted to the NETASCII format (i.e.,
1341: * you should not attempt to create a special InputStream to do this).
1342: * <p>
1343: * @param remote The name of the remote file.
1344: * @param local The local InputStream from which to read the data to
1345: * be appended to the remote file.
1346: * @return True if successfully completed, false if not.
1347: * @exception FTPConnectionClosedException
1348: * If the FTP server prematurely closes the connection as a result
1349: * of the client being idle or some other reason causing the server
1350: * to send FTP reply code 421. This exception may be caught either
1351: * as an IOException or independently as itself.
1352: * @exception CopyStreamException If an I/O error occurs while actually
1353: * transferring the file. The CopyStreamException allows you to
1354: * determine the number of bytes transferred and the IOException
1355: * causing the error. This exception may be caught either
1356: * as an IOException or independently as itself.
1357: * @exception IOException If an I/O error occurs while either sending a
1358: * command to the server or receiving a reply from the server.
1359: ***/
1360: public boolean appendFile(String remote, InputStream local)
1361: throws IOException {
1362: return __storeFile(FTPCommand.APPE, remote, local);
1363: }
1364:
1365: /***
1366: * Returns an OutputStream through which data can be written to append
1367: * to a file on the server with the given name. If the current file type
1368: * is ASCII, the returned OutputStream will convert line separators in
1369: * the file to the NETASCII format (i.e., you should not attempt to
1370: * create a special OutputStream to do this). You must close the
1371: * OutputStream when you finish writing to it. The OutputStream itself
1372: * will take care of closing the parent data connection socket upon being
1373: * closed. To finalize the file transfer you must call
1374: * {@link #completePendingCommand completePendingCommand } and
1375: * check its return value to verify success.
1376: * <p>
1377: * @param remote The name of the remote file.
1378: * @return An OutputStream through which the remote file can be appended.
1379: * If the data connection cannot be opened (e.g., the file does not
1380: * exist), null is returned (in which case you may check the reply
1381: * code to determine the exact reason for failure).
1382: * @exception FTPConnectionClosedException
1383: * If the FTP server prematurely closes the connection as a result
1384: * of the client being idle or some other reason causing the server
1385: * to send FTP reply code 421. This exception may be caught either
1386: * as an IOException or independently as itself.
1387: * @exception IOException If an I/O error occurs while either sending a
1388: * command to the server or receiving a reply from the server.
1389: ***/
1390: public OutputStream appendFileStream(String remote)
1391: throws IOException {
1392: return __storeFileStream(FTPCommand.APPE, remote);
1393: }
1394:
1395: /***
1396: * Stores a file on the server using a unique name derived from the
1397: * given name and taking input
1398: * from the given InputStream. This method does NOT close the given
1399: * InputStream. If the current file type is ASCII, line separators in
1400: * the file are transparently converted to the NETASCII format (i.e.,
1401: * you should not attempt to create a special InputStream to do this).
1402: * <p>
1403: * @param remote The name on which to base the unique name given to
1404: * the remote file.
1405: * @param local The local InputStream from which to read the file.
1406: * @return True if successfully completed, false if not.
1407: * @exception FTPConnectionClosedException
1408: * If the FTP server prematurely closes the connection as a result
1409: * of the client being idle or some other reason causing the server
1410: * to send FTP reply code 421. This exception may be caught either
1411: * as an IOException or independently as itself.
1412: * @exception CopyStreamException If an I/O error occurs while actually
1413: * transferring the file. The CopyStreamException allows you to
1414: * determine the number of bytes transferred and the IOException
1415: * causing the error. This exception may be caught either
1416: * as an IOException or independently as itself.
1417: * @exception IOException If an I/O error occurs while either sending a
1418: * command to the server or receiving a reply from the server.
1419: ***/
1420: public boolean storeUniqueFile(String remote, InputStream local)
1421: throws IOException {
1422: return __storeFile(FTPCommand.STOU, remote, local);
1423: }
1424:
1425: /***
1426: * Returns an OutputStream through which data can be written to store
1427: * a file on the server using a unique name derived from the given name.
1428: * If the current file type
1429: * is ASCII, the returned OutputStream will convert line separators in
1430: * the file to the NETASCII format (i.e., you should not attempt to
1431: * create a special OutputStream to do this). You must close the
1432: * OutputStream when you finish writing to it. The OutputStream itself
1433: * will take care of closing the parent data connection socket upon being
1434: * closed. To finalize the file transfer you must call
1435: * {@link #completePendingCommand completePendingCommand } and
1436: * check its return value to verify success.
1437: * <p>
1438: * @param remote The name on which to base the unique name given to
1439: * the remote file.
1440: * @return An OutputStream through which the remote file can be written. If
1441: * the data connection cannot be opened (e.g., the file does not
1442: * exist), null is returned (in which case you may check the reply
1443: * code to determine the exact reason for failure).
1444: * @exception FTPConnectionClosedException
1445: * If the FTP server prematurely closes the connection as a result
1446: * of the client being idle or some other reason causing the server
1447: * to send FTP reply code 421. This exception may be caught either
1448: * as an IOException or independently as itself.
1449: * @exception IOException If an I/O error occurs while either sending a
1450: * command to the server or receiving a reply from the server.
1451: ***/
1452: public OutputStream storeUniqueFileStream(String remote)
1453: throws IOException {
1454: return __storeFileStream(FTPCommand.STOU, remote);
1455: }
1456:
1457: /**
1458: * Stores a file on the server using a unique name assigned by the
1459: * server and taking input from the given InputStream. This method does
1460: * NOT close the given
1461: * InputStream. If the current file type is ASCII, line separators in
1462: * the file are transparently converted to the NETASCII format (i.e.,
1463: * you should not attempt to create a special InputStream to do this).
1464: * <p>
1465: * @param local The local InputStream from which to read the file.
1466: * @return True if successfully completed, false if not.
1467: * @exception FTPConnectionClosedException
1468: * If the FTP server prematurely closes the connection as a result
1469: * of the client being idle or some other reason causing the server
1470: * to send FTP reply code 421. This exception may be caught either
1471: * as an IOException or independently as itself.
1472: * @exception CopyStreamException If an I/O error occurs while actually
1473: * transferring the file. The CopyStreamException allows you to
1474: * determine the number of bytes transferred and the IOException
1475: * causing the error. This exception may be caught either
1476: * as an IOException or independently as itself.
1477: * @exception IOException If an I/O error occurs while either sending a
1478: * command to the server or receiving a reply from the server.
1479: */
1480: public boolean storeUniqueFile(InputStream local)
1481: throws IOException {
1482: return __storeFile(FTPCommand.STOU, null, local);
1483: }
1484:
1485: /**
1486: * Returns an OutputStream through which data can be written to store
1487: * a file on the server using a unique name assigned by the server.
1488: * If the current file type
1489: * is ASCII, the returned OutputStream will convert line separators in
1490: * the file to the NETASCII format (i.e., you should not attempt to
1491: * create a special OutputStream to do this). You must close the
1492: * OutputStream when you finish writing to it. The OutputStream itself
1493: * will take care of closing the parent data connection socket upon being
1494: * closed. To finalize the file transfer you must call
1495: * {@link #completePendingCommand completePendingCommand } and
1496: * check its return value to verify success.
1497: * <p>
1498: * @return An OutputStream through which the remote file can be written. If
1499: * the data connection cannot be opened (e.g., the file does not
1500: * exist), null is returned (in which case you may check the reply
1501: * code to determine the exact reason for failure).
1502: * @exception FTPConnectionClosedException
1503: * If the FTP server prematurely closes the connection as a result
1504: * of the client being idle or some other reason causing the server
1505: * to send FTP reply code 421. This exception may be caught either
1506: * as an IOException or independently as itself.
1507: * @exception IOException If an I/O error occurs while either sending a
1508: * command to the server or receiving a reply from the server.
1509: */
1510: public OutputStream storeUniqueFileStream() throws IOException {
1511: return __storeFileStream(FTPCommand.STOU, null);
1512: }
1513:
1514: /***
1515: * Reserve a number of bytes on the server for the next file transfer.
1516: * <p>
1517: * @param bytes The number of bytes which the server should allocate.
1518: * @return True if successfully completed, false if not.
1519: * @exception FTPConnectionClosedException
1520: * If the FTP server prematurely closes the connection as a result
1521: * of the client being idle or some other reason causing the server
1522: * to send FTP reply code 421. This exception may be caught either
1523: * as an IOException or independently as itself.
1524: * @exception IOException If an I/O error occurs while either sending a
1525: * command to the server or receiving a reply from the server.
1526: ***/
1527: public boolean allocate(int bytes) throws IOException {
1528: return FTPReply.isPositiveCompletion(allo(bytes));
1529: }
1530:
1531: /**
1532: * Reserve space on the server for the next file transfer.
1533: * <p>
1534: * @param bytes The number of bytes which the server should allocate.
1535: * @param recordSize The size of a file record.
1536: * @return True if successfully completed, false if not.
1537: * @exception FTPConnectionClosedException
1538: * If the FTP server prematurely closes the connection as a result
1539: * of the client being idle or some other reason causing the server
1540: * to send FTP reply code 421. This exception may be caught either
1541: * as an IOException or independently as itself.
1542: * @exception IOException If an I/O error occurs while either sending a
1543: * command to the server or receiving a reply from the server.
1544: */
1545: public boolean allocate(int bytes, int recordSize)
1546: throws IOException {
1547: return FTPReply.isPositiveCompletion(allo(bytes, recordSize));
1548: }
1549:
1550: /***
1551: * Restart a <code>STREAM_TRANSFER_MODE</code> file transfer starting
1552: * from the given offset. This will only work on FTP servers supporting
1553: * the REST comand for the stream transfer mode. However, most FTP
1554: * servers support this. Any subsequent file transfer will start
1555: * reading or writing the remote file from the indicated offset.
1556: * <p>
1557: * @param offset The offset into the remote file at which to start the
1558: * next file transfer.
1559: * @return True if successfully completed, false if not.
1560: * @exception FTPConnectionClosedException
1561: * If the FTP server prematurely closes the connection as a result
1562: * of the client being idle or some other reason causing the server
1563: * to send FTP reply code 421. This exception may be caught either
1564: * as an IOException or independently as itself.
1565: * @exception IOException If an I/O error occurs while either sending a
1566: * command to the server or receiving a reply from the server.
1567: ***/
1568: private boolean restart(long offset) throws IOException {
1569: __restartOffset = 0;
1570: return FTPReply.isPositiveIntermediate(rest(Long
1571: .toString(offset)));
1572: }
1573:
1574: /***
1575: * Sets the restart offset. The restart command is sent to the server
1576: * only before sending the file transfer command. When this is done,
1577: * the restart marker is reset to zero.
1578: * <p>
1579: * @param offset The offset into the remote file at which to start the
1580: * next file transfer. This must be a value greater than or
1581: * equal to zero.
1582: ***/
1583: public void setRestartOffset(long offset) {
1584: if (offset >= 0)
1585: __restartOffset = offset;
1586: }
1587:
1588: /***
1589: * Fetches the restart offset.
1590: * <p>
1591: * @return offset The offset into the remote file at which to start the
1592: * next file transfer.
1593: ***/
1594: public long getRestartOffset() {
1595: return __restartOffset;
1596: }
1597:
1598: /***
1599: * Renames a remote file.
1600: * <p>
1601: * @param from The name of the remote file to rename.
1602: * @param to The new name of the remote file.
1603: * @return True if successfully completed, false if not.
1604: * @exception FTPConnectionClosedException
1605: * If the FTP server prematurely closes the connection as a result
1606: * of the client being idle or some other reason causing the server
1607: * to send FTP reply code 421. This exception may be caught either
1608: * as an IOException or independently as itself.
1609: * @exception IOException If an I/O error occurs while either sending a
1610: * command to the server or receiving a reply from the server.
1611: ***/
1612: public boolean rename(String from, String to) throws IOException {
1613: if (!FTPReply.isPositiveIntermediate(rnfr(from)))
1614: return false;
1615:
1616: return FTPReply.isPositiveCompletion(rnto(to));
1617: }
1618:
1619: /***
1620: * Abort a transfer in progress.
1621: * <p>
1622: * @return True if successfully completed, false if not.
1623: * @exception FTPConnectionClosedException
1624: * If the FTP server prematurely closes the connection as a result
1625: * of the client being idle or some other reason causing the server
1626: * to send FTP reply code 421. This exception may be caught either
1627: * as an IOException or independently as itself.
1628: * @exception IOException If an I/O error occurs while either sending a
1629: * command to the server or receiving a reply from the server.
1630: ***/
1631: public boolean abort() throws IOException {
1632: return FTPReply.isPositiveCompletion(abor());
1633: }
1634:
1635: /***
1636: * Deletes a file on the FTP server.
1637: * <p>
1638: * @param pathname The pathname of the file to be deleted.
1639: * @return True if successfully completed, false if not.
1640: * @exception FTPConnectionClosedException
1641: * If the FTP server prematurely closes the connection as a result
1642: * of the client being idle or some other reason causing the server
1643: * to send FTP reply code 421. This exception may be caught either
1644: * as an IOException or independently as itself.
1645: * @exception IOException If an I/O error occurs while either sending a
1646: * command to the server or receiving a reply from the server.
1647: ***/
1648: public boolean deleteFile(String pathname) throws IOException {
1649: return FTPReply.isPositiveCompletion(dele(pathname));
1650: }
1651:
1652: /***
1653: * Removes a directory on the FTP server (if empty).
1654: * <p>
1655: * @param pathname The pathname of the directory to remove.
1656: * @return True if successfully completed, false if not.
1657: * @exception FTPConnectionClosedException
1658: * If the FTP server prematurely closes the connection as a result
1659: * of the client being idle or some other reason causing the server
1660: * to send FTP reply code 421. This exception may be caught either
1661: * as an IOException or independently as itself.
1662: * @exception IOException If an I/O error occurs while either sending a
1663: * command to the server or receiving a reply from the server.
1664: ***/
1665: public boolean removeDirectory(String pathname) throws IOException {
1666: return FTPReply.isPositiveCompletion(rmd(pathname));
1667: }
1668:
1669: /***
1670: * Creates a new subdirectory on the FTP server in the current directory
1671: * (if a relative pathname is given) or where specified (if an absolute
1672: * pathname is given).
1673: * <p>
1674: * @param pathname The pathname of the directory to create.
1675: * @return True if successfully completed, false if not.
1676: * @exception FTPConnectionClosedException
1677: * If the FTP server prematurely closes the connection as a result
1678: * of the client being idle or some other reason causing the server
1679: * to send FTP reply code 421. This exception may be caught either
1680: * as an IOException or independently as itself.
1681: * @exception IOException If an I/O error occurs while either sending a
1682: * command to the server or receiving a reply from the server.
1683: ***/
1684: public boolean makeDirectory(String pathname) throws IOException {
1685: return FTPReply.isPositiveCompletion(mkd(pathname));
1686: }
1687:
1688: /***
1689: * Returns the pathname of the current working directory.
1690: * <p>
1691: * @return The pathname of the current working directory. If it cannot
1692: * be obtained, returns null.
1693: * @exception FTPConnectionClosedException
1694: * If the FTP server prematurely closes the connection as a result
1695: * of the client being idle or some other reason causing the server
1696: * to send FTP reply code 421. This exception may be caught either
1697: * as an IOException or independently as itself.
1698: * @exception IOException If an I/O error occurs while either sending a
1699: * command to the server or receiving a reply from the server.
1700: ***/
1701: public String printWorkingDirectory() throws IOException {
1702: if (pwd() != FTPReply.PATHNAME_CREATED)
1703: return null;
1704:
1705: return __parsePathname((String) _replyLines.elementAt(0));
1706: }
1707:
1708: /**
1709: * Send a site specific command.
1710: * @param arguments The site specific command and arguments.
1711: * @return True if successfully completed, false if not.
1712: * @exception FTPConnectionClosedException
1713: * If the FTP server prematurely closes the connection as a result
1714: * of the client being idle or some other reason causing the server
1715: * to send FTP reply code 421. This exception may be caught either
1716: * as an IOException or independently as itself.
1717: * @exception IOException If an I/O error occurs while either sending a
1718: * command to the server or receiving a reply from the server.
1719: */
1720: public boolean sendSiteCommand(String arguments) throws IOException {
1721: return FTPReply.isPositiveCompletion(site(arguments));
1722: }
1723:
1724: /***
1725: * Fetches the system type name from the server and returns the string.
1726: * This value is cached for the duration of the connection after the
1727: * first call to this method. In other words, only the first time
1728: * that you invoke this method will it issue a SYST command to the
1729: * FTP server. FTPClient will remember the value and return the
1730: * cached value until a call to disconnect.
1731: * <p>
1732: * @return The system type name obtained from the server. null if the
1733: * information could not be obtained.
1734: * @exception FTPConnectionClosedException
1735: * If the FTP server prematurely closes the connection as a result
1736: * of the client being idle or some other reason causing the server
1737: * to send FTP reply code 421. This exception may be caught either
1738: * as an IOException or independently as itself.
1739: * @exception IOException If an I/O error occurs while either sending a
1740: * command to the server or receiving a reply from the server.
1741: ***/
1742: public String getSystemName() throws IOException {
1743: //if (syst() == FTPReply.NAME_SYSTEM_TYPE)
1744: // Technically, we should expect a NAME_SYSTEM_TYPE response, but
1745: // in practice FTP servers deviate, so we soften the condition to
1746: // a positive completion.
1747: if (__systemName == null
1748: && FTPReply.isPositiveCompletion(syst()))
1749: __systemName = ((String) _replyLines.elementAt(0))
1750: .substring(4);
1751:
1752: return __systemName;
1753: }
1754:
1755: /***
1756: * Fetches the system help information from the server and returns the
1757: * full string.
1758: * <p>
1759: * @return The system help string obtained from the server. null if the
1760: * information could not be obtained.
1761: * @exception FTPConnectionClosedException
1762: * If the FTP server prematurely closes the connection as a result
1763: * of the client being idle or some other reason causing the server
1764: * to send FTP reply code 421. This exception may be caught either
1765: * as an IOException or independently as itself.
1766: * @exception IOException If an I/O error occurs while either sending a
1767: * command to the server or receiving a reply from the server.
1768: ***/
1769: public String listHelp() throws IOException {
1770: if (FTPReply.isPositiveCompletion(help()))
1771: return getReplyString();
1772: return null;
1773: }
1774:
1775: /**
1776: * Fetches the help information for a given command from the server and
1777: * returns the full string.
1778: * @param command The command on which to ask for help.
1779: * @return The command help string obtained from the server. null if the
1780: * information could not be obtained.
1781: * @exception FTPConnectionClosedException
1782: * If the FTP server prematurely closes the connection as a result
1783: * of the client being idle or some other reason causing the server
1784: * to send FTP reply code 421. This exception may be caught either
1785: * as an IOException or independently as itself.
1786: * @exception IOException If an I/O error occurs while either sending a
1787: * command to the server or receiving a reply from the server.
1788: */
1789: public String listHelp(String command) throws IOException {
1790: if (FTPReply.isPositiveCompletion(help(command)))
1791: return getReplyString();
1792: return null;
1793: }
1794:
1795: /***
1796: * Sends a NOOP command to the FTP server. This is useful for preventing
1797: * server timeouts.
1798: * <p>
1799: * @return True if successfully completed, false if not.
1800: * @exception FTPConnectionClosedException
1801: * If the FTP server prematurely closes the connection as a result
1802: * of the client being idle or some other reason causing the server
1803: * to send FTP reply code 421. This exception may be caught either
1804: * as an IOException or independently as itself.
1805: * @exception IOException If an I/O error occurs while either sending a
1806: * command to the server or receiving a reply from the server.
1807: ***/
1808: public boolean sendNoOp() throws IOException {
1809: return FTPReply.isPositiveCompletion(noop());
1810: }
1811:
1812: /***
1813: * Obtain a list of filenames in a directory (or just the name of a given
1814: * file, which is not particularly useful). This information is obtained
1815: * through the NLST command. If the given pathname is a directory and
1816: * contains no files, a zero length array is returned only
1817: * if the FTP server returned a positive completion code, otherwise
1818: * null is returned (the FTP server returned a 550 error No files found.).
1819: * If the directory is not empty, an array of filenames in the directory is
1820: * returned. If the pathname corresponds
1821: * to a file, only that file will be listed. The server may or may not
1822: * expand glob expressions.
1823: * <p>
1824: * @param pathname The file or directory to list.
1825: * @return The list of filenames contained in the given path. null if
1826: * the list could not be obtained. If there are no filenames in
1827: * the directory, a zero-length array is returned.
1828: * @exception FTPConnectionClosedException
1829: * If the FTP server prematurely closes the connection as a result
1830: * of the client being idle or some other reason causing the server
1831: * to send FTP reply code 421. This exception may be caught either
1832: * as an IOException or independently as itself.
1833: * @exception IOException If an I/O error occurs while either sending a
1834: * command to the server or receiving a reply from the server.
1835: ***/
1836: public String[] listNames(String pathname) throws IOException {
1837: String line;
1838: Socket socket;
1839: BufferedReader reader;
1840: Vector results;
1841:
1842: if ((socket = _openDataConnection_(FTPCommand.NLST, pathname)) == null)
1843: return null;
1844:
1845: reader = new BufferedReader(new InputStreamReader(socket
1846: .getInputStream(), getControlEncoding()));
1847:
1848: results = new Vector();
1849: while ((line = reader.readLine()) != null)
1850: results.addElement(line);
1851: reader.close();
1852: socket.close();
1853:
1854: if (completePendingCommand()) {
1855: String[] result;
1856: result = new String[results.size()];
1857: results.copyInto(result);
1858: return result;
1859: }
1860:
1861: return null;
1862: }
1863:
1864: /***
1865: * Obtain a list of filenames in the current working directory
1866: * This information is obtained through the NLST command. If the current
1867: * directory contains no files, a zero length array is returned only
1868: * if the FTP server returned a positive completion code, otherwise,
1869: * null is returned (the FTP server returned a 550 error No files found.).
1870: * If the directory is not empty, an array of filenames in the directory is
1871: * returned.
1872: * <p>
1873: * @return The list of filenames contained in the current working
1874: * directory. null if the list could not be obtained.
1875: * If there are no filenames in the directory, a zero-length array
1876: * is returned.
1877: * @exception FTPConnectionClosedException
1878: * If the FTP server prematurely closes the connection as a result
1879: * of the client being idle or some other reason causing the server
1880: * to send FTP reply code 421. This exception may be caught either
1881: * as an IOException or independently as itself.
1882: * @exception IOException If an I/O error occurs while either sending a
1883: * command to the server or receiving a reply from the server.
1884: ***/
1885: public String[] listNames() throws IOException {
1886: return listNames(null);
1887: }
1888:
1889: /**
1890: * Using the supplied <code>parserKey</code>, obtain a list
1891: * of file information for the current working directory or for just a
1892: * single file.
1893: * <p>
1894: * If <code>key</code> is null, this object will try to autodetect
1895: * the system-type/parser-type by calling the SYST command.
1896: * <p>
1897: * Under the DefaultFTPFileEntryParserFactory, which is used unless a
1898: * different factory has been specified, the key
1899: * can be either a recognized System type for which a parser has been
1900: * defined, or the fully qualified class name of a class that implements
1901: * org.apache.commons.net.ftp.FTPFileEntryParser.
1902: * <p>
1903: * This information is obtained through the LIST command. The contents of
1904: * the returned array is determined by the<code> FTPFileEntryParser </code>
1905: * used.
1906: * <p>
1907: * @param parserKey This is a "handle" which the parser factory used
1908: * must be able to resolve into a class implementing
1909: * FTPFileEntryParser.
1910: * <p>
1911: * In the DefaultFTPFileEntryParserFactory, this
1912: * may either be a specific key identifying a server type,
1913: * which is used to identify a parser type,
1914: * or the fully qualified class name of the parser. See
1915: * DefaultFTPFileEntryParserFactory.createFileEntryParser
1916: * for full details.
1917: * <p>
1918: * If this parameter is null, will attempt to generate a key
1919: * by running the SYST command. This should cause no problem
1920: * with the functionality implemented in the
1921: * DefaultFTPFileEntryParserFactory, but may not map so well
1922: * to an alternative user-created factory. If that is the
1923: * case, calling this routine with a null parameter and a
1924: * custom parser factory may not be advisable.
1925: * <p>
1926: * @param pathname The file or directory to list. Since the server may
1927: * or may not expand glob expressions, using them here
1928: * is not recommended and may well cause this method to
1929: * fail.
1930: *
1931: * @return The list of file information contained in the given path in
1932: * the format determined by the parser represented by the
1933: * <code> parserKey </code> parameter.
1934: * <p><b>
1935: * NOTE:</b> This array may contain null members if any of the
1936: * individual file listings failed to parse. The caller should
1937: * check each entry for null before referencing it.
1938: * @exception FTPConnectionClosedException
1939: * If the FTP server prematurely closes the connection
1940: * as a result of the client being idle or some other
1941: * reason causing the server to send FTP reply code 421.
1942: * This exception may be caught either as an IOException
1943: * or independently as itself.
1944: * @exception IOException
1945: * If an I/O error occurs while either sending a
1946: * command to the server or receiving a reply
1947: * from the server.
1948: * @exception ParserInitializationException
1949: * Thrown if the parserKey parameter cannot be
1950: * resolved by the selected parser factory.
1951: * In the DefaultFTPEntryParserFactory, this will
1952: * happen when parserKey is neither
1953: * the fully qualified class name of a class
1954: * implementing the interface
1955: * org.apache.commons.net.ftp.FTPFileEntryParser
1956: * nor a string containing one of the recognized keys
1957: * mapping to such a parser or if class loader
1958: * security issues prevent its being loaded.
1959: * @see org.apache.commons.net.ftp.parser.DefaultFTPFileEntryParserFactory
1960: * @see org.apache.commons.net.ftp.parser.FTPFileEntryParserFactory
1961: * @see org.apache.commons.net.ftp.FTPFileEntryParser
1962: * @deprecated use {@link #listFiles() listFiles()} or
1963: * {@link #listFiles(String) listFiles(String)} instead and specify the
1964: * parser Key in an {@link #FTPClientConfig FTPClientConfig} object instead.
1965: */
1966: public FTPFile[] listFiles(String parserKey, String pathname)
1967: throws IOException {
1968: FTPListParseEngine engine = initiateListParsing(parserKey,
1969: pathname);
1970: return engine.getFiles();
1971: }
1972:
1973: /**
1974: * Using the default system autodetect mechanism, obtain a
1975: * list of file information for the current working directory
1976: * or for just a single file.
1977: * <p>
1978: * This information is obtained through the LIST command. The contents of
1979: * the returned array is determined by the<code> FTPFileEntryParser </code>
1980: * used.
1981: * <p>
1982: * @param pathname The file or directory to list. Since the server may
1983: * or may not expand glob expressions, using them here
1984: * is not recommended and may well cause this method to
1985: * fail.
1986: *
1987: * @return The list of file information contained in the given path in
1988: * the format determined by the autodetection mechanism
1989: * @exception FTPConnectionClosedException
1990: * If the FTP server prematurely closes the connection
1991: * as a result of the client being idle or some other
1992: * reason causing the server to send FTP reply code 421.
1993: * This exception may be caught either as an IOException
1994: * or independently as itself.
1995: * @exception IOException
1996: * If an I/O error occurs while either sending a
1997: * command to the server or receiving a reply
1998: * from the server.
1999: * @exception ParserInitializationException
2000: * Thrown if the parserKey parameter cannot be
2001: * resolved by the selected parser factory.
2002: * In the DefaultFTPEntryParserFactory, this will
2003: * happen when parserKey is neither
2004: * the fully qualified class name of a class
2005: * implementing the interface
2006: * org.apache.commons.net.ftp.FTPFileEntryParser
2007: * nor a string containing one of the recognized keys
2008: * mapping to such a parser or if class loader
2009: * security issues prevent its being loaded.
2010: * @see org.apache.commons.net.ftp.parser.DefaultFTPFileEntryParserFactory
2011: * @see org.apache.commons.net.ftp.parser.FTPFileEntryParserFactory
2012: * @see org.apache.commons.net.ftp.FTPFileEntryParser
2013: */
2014: public FTPFile[] listFiles(String pathname) throws IOException {
2015: String key = null;
2016: FTPListParseEngine engine = initiateListParsing(key, pathname);
2017: return engine.getFiles();
2018:
2019: }
2020:
2021: /**
2022: * Using the default system autodetect mechanism, obtain a
2023: * list of file information for the current working directory.
2024: * <p>
2025: * This information is obtained through the LIST command. The contents of
2026: * the returned array is determined by the<code> FTPFileEntryParser </code>
2027: * used.
2028: * <p>
2029: * @return The list of file information contained in the current directory
2030: * in the format determined by the autodetection mechanism.
2031: * <p><b>
2032: * NOTE:</b> This array may contain null members if any of the
2033: * individual file listings failed to parse. The caller should
2034: * check each entry for null before referencing it.
2035: * @exception FTPConnectionClosedException
2036: * If the FTP server prematurely closes the connection
2037: * as a result of the client being idle or some other
2038: * reason causing the server to send FTP reply code 421.
2039: * This exception may be caught either as an IOException
2040: * or independently as itself.
2041: * @exception IOException
2042: * If an I/O error occurs while either sending a
2043: * command to the server or receiving a reply
2044: * from the server.
2045: * @exception ParserInitializationException
2046: * Thrown if the parserKey parameter cannot be
2047: * resolved by the selected parser factory.
2048: * In the DefaultFTPEntryParserFactory, this will
2049: * happen when parserKey is neither
2050: * the fully qualified class name of a class
2051: * implementing the interface
2052: * org.apache.commons.net.ftp.FTPFileEntryParser
2053: * nor a string containing one of the recognized keys
2054: * mapping to such a parser or if class loader
2055: * security issues prevent its being loaded.
2056: * @see org.apache.commons.net.ftp.parser.DefaultFTPFileEntryParserFactory
2057: * @see org.apache.commons.net.ftp.parser.FTPFileEntryParserFactory
2058: * @see org.apache.commons.net.ftp.FTPFileEntryParser
2059: */
2060: public FTPFile[] listFiles() throws IOException {
2061: return listFiles((String) null);
2062: }
2063:
2064: /**
2065: * Using the default autodetect mechanism, initialize an FTPListParseEngine
2066: * object containing a raw file information for the current working
2067: * directory on the server
2068: * This information is obtained through the LIST command. This object
2069: * is then capable of being iterated to return a sequence of FTPFile
2070: * objects with information filled in by the
2071: * <code> FTPFileEntryParser </code> used.
2072: * <p>
2073: * This method differs from using the listFiles() methods in that
2074: * expensive FTPFile objects are not created until needed which may be
2075: * an advantage on large lists.
2076: *
2077: * @return A FTPListParseEngine object that holds the raw information and
2078: * is capable of providing parsed FTPFile objects, one for each file
2079: * containing information contained in the given path in the format
2080: * determined by the <code> parser </code> parameter. Null will be
2081: * returned if a data connection cannot be opened. If the current working
2082: * directory contains no files, an empty array will be the return.
2083: *
2084: * @exception FTPConnectionClosedException
2085: * If the FTP server prematurely closes the connection as a result
2086: * of the client being idle or some other reason causing the server
2087: * to send FTP reply code 421. This exception may be caught either
2088: * as an IOException or independently as itself.
2089: * @exception IOException
2090: * If an I/O error occurs while either sending a
2091: * command to the server or receiving a reply from the server.
2092: * @exception ParserInitializationException
2093: * Thrown if the autodetect mechanism cannot
2094: * resolve the type of system we are connected with.
2095: * @see FTPListParseEngine
2096: */
2097: public FTPListParseEngine initiateListParsing() throws IOException {
2098: return initiateListParsing((String) null);
2099: }
2100:
2101: /**
2102: * Using the default autodetect mechanism, initialize an FTPListParseEngine
2103: * object containing a raw file information for the supplied directory.
2104: * This information is obtained through the LIST command. This object
2105: * is then capable of being iterated to return a sequence of FTPFile
2106: * objects with information filled in by the
2107: * <code> FTPFileEntryParser </code> used.
2108: * <p>
2109: * The server may or may not expand glob expressions. You should avoid
2110: * using glob expressions because the return format for glob listings
2111: * differs from server to server and will likely cause this method to fail.
2112: * <p>
2113: * This method differs from using the listFiles() methods in that
2114: * expensive FTPFile objects are not created until needed which may be
2115: * an advantage on large lists.
2116: * <p>
2117: * <pre>
2118: * FTPClient f=FTPClient();
2119: * f.connect(server);
2120: * f.login(username, password);
2121: * FTPListParseEngine engine = f.initiateListParsing(directory);
2122: *
2123: * while (engine.hasNext()) {
2124: * FTPFile[] files = engine.getNext(25); // "page size" you want
2125: * //do whatever you want with these files, display them, etc.
2126: * //expensive FTPFile objects not created until needed.
2127: * }
2128: * </pre>
2129: *
2130: * @return A FTPListParseEngine object that holds the raw information and
2131: * is capable of providing parsed FTPFile objects, one for each file
2132: * containing information contained in the given path in the format
2133: * determined by the <code> parser </code> parameter. Null will be
2134: * returned if a data connection cannot be opened. If the current working
2135: * directory contains no files, an empty array will be the return.
2136: *
2137: * @exception FTPConnectionClosedException
2138: * If the FTP server prematurely closes the connection as a result
2139: * of the client being idle or some other reason causing the server
2140: * to send FTP reply code 421. This exception may be caught either
2141: * as an IOException or independently as itself.
2142: * @exception IOException
2143: * If an I/O error occurs while either sending a
2144: * command to the server or receiving a reply from the server.
2145: * @exception ParserInitializationException
2146: * Thrown if the autodetect mechanism cannot
2147: * resolve the type of system we are connected with.
2148: * @see FTPListParseEngine
2149: */
2150: public FTPListParseEngine initiateListParsing(String pathname)
2151: throws IOException {
2152: String key = null;
2153: return initiateListParsing(key, pathname);
2154: }
2155:
2156: /**
2157: * Using the supplied parser key, initialize an FTPListParseEngine
2158: * object containing a raw file information for the supplied directory.
2159: * This information is obtained through the LIST command. This object
2160: * is then capable of being iterated to return a sequence of FTPFile
2161: * objects with information filled in by the
2162: * <code> FTPFileEntryParser </code> used.
2163: * <p>
2164: * The server may or may not expand glob expressions. You should avoid
2165: * using glob expressions because the return format for glob listings
2166: * differs from server to server and will likely cause this method to fail.
2167: * <p>
2168: * This method differs from using the listFiles() methods in that
2169: * expensive FTPFile objects are not created until needed which may be
2170: * an advantage on large lists.
2171: *
2172: * @param parserKey A string representing a designated code or fully-qualified
2173: * class name of an <code> FTPFileEntryParser </code> that should be
2174: * used to parse each server file listing.
2175: *
2176: * @return A FTPListParseEngine object that holds the raw information and
2177: * is capable of providing parsed FTPFile objects, one for each file
2178: * containing information contained in the given path in the format
2179: * determined by the <code> parser </code> parameter. Null will be
2180: * returned if a data connection cannot be opened. If the current working
2181: * directory contains no files, an empty array will be the return.
2182: *
2183: * @exception FTPConnectionClosedException
2184: * If the FTP server prematurely closes the connection as a result
2185: * of the client being idle or some other reason causing the server
2186: * to send FTP reply code 421. This exception may be caught either
2187: * as an IOException or independently as itself.
2188: * @exception IOException
2189: * If an I/O error occurs while either sending a
2190: * command to the server or receiving a reply from the server.
2191: * @exception ParserInitializationException
2192: * Thrown if the parserKey parameter cannot be
2193: * resolved by the selected parser factory.
2194: * In the DefaultFTPEntryParserFactory, this will
2195: * happen when parserKey is neither
2196: * the fully qualified class name of a class
2197: * implementing the interface
2198: * org.apache.commons.net.ftp.FTPFileEntryParser
2199: * nor a string containing one of the recognized keys
2200: * mapping to such a parser or if class loader
2201: * security issues prevent its being loaded.
2202: * @see FTPListParseEngine
2203: */
2204: public FTPListParseEngine initiateListParsing(String parserKey,
2205: String pathname) throws IOException {
2206: // We cache the value to avoid creation of a new object every
2207: // time a file listing is generated.
2208: if (__entryParser == null) {
2209: if (null != parserKey) {
2210: // if a parser key was supplied in the parameters,
2211: // use that to create the paraser
2212: __entryParser = __parserFactory
2213: .createFileEntryParser(parserKey);
2214:
2215: } else {
2216: // if no parserKey was supplied, check for a configuration
2217: // in the params, and if non-null, use that.
2218: if (null != __configuration) {
2219: __entryParser = __parserFactory
2220: .createFileEntryParser(__configuration);
2221: } else {
2222: // if a parserKey hasn't been supplied, and a configuration
2223: // hasn't been supplied, then autodetect by calling
2224: // the SYST command and use that to choose the parser.
2225: __entryParser = __parserFactory
2226: .createFileEntryParser(getSystemName());
2227: }
2228: }
2229: }
2230:
2231: return initiateListParsing(__entryParser, pathname);
2232:
2233: }
2234:
2235: /**
2236: * private method through which all listFiles() and
2237: * initiateListParsing methods pass once a parser is determined.
2238: *
2239: * @exception FTPConnectionClosedException
2240: * If the FTP server prematurely closes the connection as a result
2241: * of the client being idle or some other reason causing the server
2242: * to send FTP reply code 421. This exception may be caught either
2243: * as an IOException or independently as itself.
2244: * @exception IOException
2245: * If an I/O error occurs while either sending a
2246: * command to the server or receiving a reply from the server.
2247: * @see FTPListParseEngine
2248: */
2249: private FTPListParseEngine initiateListParsing(
2250: FTPFileEntryParser parser, String pathname)
2251: throws IOException {
2252: Socket socket;
2253:
2254: FTPListParseEngine engine = new FTPListParseEngine(parser);
2255: if ((socket = _openDataConnection_(FTPCommand.LIST, pathname)) == null) {
2256: return engine;
2257: }
2258:
2259: engine.readServerList(socket.getInputStream(),
2260: getControlEncoding());
2261:
2262: socket.close();
2263:
2264: completePendingCommand();
2265: return engine;
2266: }
2267:
2268: /***
2269: * Issue the FTP STAT command to the server.
2270: * <p>
2271: * @return The status information returned by the server.
2272: * @exception FTPConnectionClosedException
2273: * If the FTP server prematurely closes the connection as a result
2274: * of the client being idle or some other reason causing the server
2275: * to send FTP reply code 421. This exception may be caught either
2276: * as an IOException or independently as itself.
2277: * @exception IOException If an I/O error occurs while either sending a
2278: * command to the server or receiving a reply from the server.
2279: ***/
2280: public String getStatus() throws IOException {
2281: if (FTPReply.isPositiveCompletion(stat()))
2282: return getReplyString();
2283: return null;
2284: }
2285:
2286: /***
2287: * Issue the FTP STAT command to the server for a given pathname. This
2288: * should produce a listing of the file or directory.
2289: * <p>
2290: * @return The status information returned by the server.
2291: * @exception FTPConnectionClosedException
2292: * If the FTP server prematurely closes the connection as a result
2293: * of the client being idle or some other reason causing the server
2294: * to send FTP reply code 421. This exception may be caught either
2295: * as an IOException or independently as itself.
2296: * @exception IOException If an I/O error occurs while either sending a
2297: * command to the server or receiving a reply from the server.
2298: ***/
2299: public String getStatus(String pathname) throws IOException {
2300: if (FTPReply.isPositiveCompletion(stat(pathname)))
2301: return getReplyString();
2302: return null;
2303: }
2304:
2305: /**
2306: * Using a programmer specified <code> FTPFileListParser </code>, obtain a
2307: * list of file information for a directory or information for
2308: * just a single file. This information is obtained through the LIST
2309: * command. The contents of the returned array is determined by the
2310: * <code> FTPFileListParser </code> used.
2311: * The server may or may not expand glob expressions. You should avoid
2312: * using glob expressions because the return format for glob listings
2313: * differs from server to server and will likely cause this method to fail.
2314: * <p>
2315: * @param parser The <code> FTPFileListParser </code> that should be
2316: * used to parse the server file listing.
2317: * @param pathname The file or directory to list.
2318: * @return The list of file information contained in the given path in
2319: * the format determined by the <code> parser </code> parameter.
2320: * <p><b>
2321: * NOTE:</b> This array may contain null members if any of the
2322: * individual file listings failed to parse. The caller should
2323: * check each entry for null before referencing it.
2324: * @exception FTPConnectionClosedException
2325: * If the FTP server prematurely closes the connection as a result
2326: * of the client being idle or some other reason causing the server
2327: * to send FTP reply code 421. This exception may be caught either
2328: * as an IOException or independently as itself.
2329: * @exception IOException If an I/O error occurs while either sending a
2330: * command to the server or receiving a reply from the server.
2331: *
2332: * @return The list of file information contained in the given path in
2333: * the format determined by<code> parserKey </code>parameter.
2334: * <p><b>
2335: * NOTE:</b> This array may contain null members if any of the
2336: * individual file listings failed to parse. The caller should
2337: * check each entry for null before referencing it.
2338: *
2339: * @exception IOException
2340: * @since 5 Jan 2004
2341: * @deprecated use listFiles(String parserKey, String pathname) instead
2342: */
2343: public FTPFile[] listFiles(FTPFileListParser parser, String pathname)
2344: throws IOException {
2345: Socket socket;
2346: FTPFile[] results;
2347:
2348: if ((socket = _openDataConnection_(FTPCommand.LIST, pathname)) == null)
2349: return new FTPFile[0];
2350:
2351: results = parser.parseFileList(socket.getInputStream(),
2352: getControlEncoding());
2353:
2354: socket.close();
2355:
2356: completePendingCommand();
2357:
2358: return results;
2359: }
2360:
2361: /**
2362: * Using a programmer specified <code> FTPFileListParser </code>,
2363: * obtain a list of file information for the current working directory.
2364: * This information is obtained through the LIST command.
2365: * The contents of the array returned is determined by the
2366: * <code> FTPFileListParser </code> used.
2367: * <p>
2368: *
2369: * @param parser The <code> FTPFileListParser </code> that should be
2370: * used to parse the server file listing.
2371: *
2372: * @return The list of file information contained in the given path in
2373: * the format determined by the <code> parser </code> parameter.
2374: * <p><b>
2375: * NOTE:</b> This array may contain null members if any of the
2376: * individual file listings failed to parse. The caller should
2377: * check each entry for null before referencing it.
2378: * @exception FTPConnectionClosedException
2379: * If the FTP server prematurely closes the connection as a result
2380: * of the client being idle or some other reason causing the server
2381: * to send FTP reply code 421. This exception may be caught either
2382: * as an IOException or independently as itself.
2383: * @exception IOException
2384: * If an I/O error occurs while either sending a
2385: * command to the server or receiving a reply from the server.
2386: * @exception IOException
2387: * @since 5 Jan 2004
2388: * @deprecated use listFiles(String parserKey) instead.
2389: */
2390: public FTPFile[] listFiles(FTPFileListParser parser)
2391: throws IOException {
2392: return listFiles(parser, null);
2393: }
2394:
2395: /**
2396: * Using a programmer specified <code> FTPFileEntryParser </code>,
2397: * initialize an object containing a raw file information for the
2398: * current working directory. This information is obtained through
2399: * the LIST command. This object is then capable of being iterated to
2400: * return a sequence of FTPFile objects with information filled in by the
2401: * <code> FTPFileEntryParser </code> used.
2402: * <p>
2403: * The server may or may not expand glob expressions. You should avoid
2404: * using glob expressions because the return format for glob listings
2405: * differs from server to server and will likely cause this method to fail.
2406: * <p>
2407: * This method differs from using the listFiles() methods in that
2408: * expensive FTPFile objects are not created until needed which may be
2409: * an advantage on large lists.
2410: *
2411: * @param parser The <code> FTPFileEntryParser </code> that should be
2412: * used to parse each server file listing.
2413: *
2414: * @return An iteratable object that holds the raw information and is
2415: * capable of providing parsed FTPFile objects, one for each file containing
2416: * information contained in the given path in the format determined by the
2417: * <code> parser </code> parameter. Null will be returned if a
2418: * data connection cannot be opened. If the current working directory
2419: * contains no files, an empty array will be the return.
2420: * <pre>
2421: * FTPClient f=FTPClient();
2422: * f.connect(server);
2423: * f.login(username, password);
2424: * FTPFileList list = f.createFileList(directory, parser);
2425: * FTPFileIterator iter = list.iterator();
2426: *
2427: * while (iter.hasNext()) {
2428: * FTPFile[] files = iter.getNext(25); // "page size" you want
2429: * //do whatever you want with these files, display them, etc.
2430: * //expensive FTPFile objects not created until needed.
2431: * }
2432: * </pre>
2433: *
2434: * @exception FTPConnectionClosedException
2435: * If the FTP server prematurely closes the connection as a result
2436: * of the client being idle or some other reason causing the server
2437: * to send FTP reply code 421. This exception may be caught either
2438: * as an IOException or independently as itself.
2439: * @exception IOException
2440: * If an I/O error occurs while either sending a
2441: * command to the server or receiving a reply from the server.
2442: * @deprecated - use initiateListParsing(FTPFileEntryParser) method instead.
2443: * @see FTPFileList
2444: */
2445: public FTPFileList createFileList(FTPFileEntryParser parser)
2446: throws IOException {
2447: return createFileList(null, parser);
2448: }
2449:
2450: /**
2451: * Using a programmer specified <code> FTPFileEntryParser </code>,
2452: * initialize an object containing a raw file information for a directory
2453: * or information for a single file. This information is obtained through
2454: * the LIST command. This object is then capable of being iterated to
2455: * return a sequence of FTPFile objects with information filled in by the
2456: * <code> FTPFileEntryParser </code> used.
2457: * The server may or may not expand glob expressions. You should avoid
2458: * using glob expressions because the return format for glob listings
2459: * differs from server to server and will likely cause this method to fail.
2460: * <p>
2461: * @param parser The <code> FTPFileEntryParser </code> that should be
2462: * used to parse each server file listing.
2463: * @param pathname The file or directory to list.
2464: * @return An iteratable object that holds the raw information and is
2465: * capable of providing parsed FTPFile objects, one for each file containing
2466: * information contained in the given path in the format determined by the
2467: * <code> parser </code> parameter. Null will be returned if a
2468: * data connection cannot be opened. If the supplied path contains
2469: * no files, an empty array will be the return.
2470: * @exception FTPConnectionClosedException
2471: * If the FTP server prematurely closes the connection as a result
2472: * of the client being idle or some other reason causing the server
2473: * to send FTP reply code 421. This exception may be caught either
2474: * as an IOException or independently as itself.
2475: * @exception IOException If an I/O error occurs while either sending a
2476: * command to the server or receiving a reply from the server.
2477: * @deprecated - use initiateListParsing(String, FTPFileEntryParser)
2478: * method instead.
2479: * @see FTPFileList
2480: */
2481: public FTPFileList createFileList(String pathname,
2482: FTPFileEntryParser parser) throws IOException {
2483: Socket socket;
2484:
2485: if ((socket = _openDataConnection_(FTPCommand.LIST, pathname)) == null) {
2486: return null;
2487: }
2488:
2489: FTPFileList list = FTPFileList.create(socket.getInputStream(),
2490: parser);
2491:
2492: socket.close();
2493:
2494: completePendingCommand();
2495: return list;
2496: }
2497:
2498: /**
2499: * Set the internal buffer size.
2500: *
2501: * @param bufSize The size of the buffer
2502: */
2503: public void setBufferSize(int bufSize) {
2504: __bufferSize = bufSize;
2505: }
2506:
2507: /**
2508: * Retrieve the current internal buffer size.
2509: * @return The current buffer size.
2510: */
2511: public int getBufferSize() {
2512: return __bufferSize;
2513: }
2514:
2515: /**
2516: * Implementation of the {@link Configurable Configurable} interface.
2517: * In the case of this class, configuring merely makes the config object available for the
2518: * factory methods that construct parsers.
2519: * @param config {@link FTPClientConfig FTPClientConfig} object used to
2520: * provide non-standard configurations to the parser.
2521: * @since 1.4
2522: */
2523: public void configure(FTPClientConfig config) {
2524: this .__configuration = config;
2525: }
2526:
2527: }
2528:
2529: /* Emacs configuration
2530: * Local variables: **
2531: * mode: java **
2532: * c-basic-offset: 4 **
2533: * indent-tabs-mode: nil **
2534: * End: **
2535: */
|