001: /*
002: * Copyright 2001-2005 The Apache Software Foundation
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.net.ftp;
017:
018: import java.io.BufferedReader;
019: import java.io.IOException;
020: import java.util.List;
021:
022: /**
023: * FTPFileEntryParser defines the interface for parsing a single FTP file
024: * listing and converting that information into an
025: * {@link org.apache.commons.net.ftp.FTPFile} instance.
026: * Sometimes you will want to parse unusual listing formats, in which
027: * case you would create your own implementation of FTPFileEntryParser and
028: * if necessary, subclass FTPFile.
029: * <p>
030: * Here are some examples showing how to use one of the classes that
031: * implement this interface.
032: * <p>
033: * The first example shows how to get an <b>iterable</b> list of files in which the
034: * more expensive <code>FTPFile</code> objects are not created until needed. This
035: * is suitable for paged displays. It requires that a parser object be created
036: * beforehand: <code>parser</code> is an object (in the package
037: * <code>org.apache.commons.net.ftp.parser</code>)
038: * implementing this inteface.
039: *
040: * <pre>
041: * FTPClient f=FTPClient();
042: * f.connect(server);
043: * f.login(username, password);
044: * FTPFileList list = f.createFileList(directory, parser);
045: * FTPFileIterator iter = list.iterator();
046: *
047: * while (iter.hasNext()) {
048: * FTPFile[] files = iter.getNext(25); // "page size" you want
049: * //do whatever you want with these files, display them, etc.
050: * //expensive FTPFile objects not created until needed.
051: * }
052: * </pre>
053: *
054: * The second example uses the revised <code>FTPClient.listFiles()</code>
055: * API to pull the whole list from the subfolder <code>subfolder</code> in
056: * one call, attempting to automatically detect the parser type. This
057: * method, without a parserKey parameter, indicates that autodection should
058: * be used.
059: *
060: * <pre>
061: * FTPClient f=FTPClient();
062: * f.connect(server);
063: * f.login(username, password);
064: * FTPFile[] files = f.listFiles("subfolder");
065: * </pre>
066: *
067: * The third example uses the revised <code>FTPClient.listFiles()</code>>
068: * API to pull the whole list from the current working directory in one call,
069: * but specifying by classname the parser to be used. For this particular
070: * parser class, this approach is necessary since there is no way to
071: * autodetect this server type.
072: *
073: * <pre>
074: * FTPClient f=FTPClient();
075: * f.connect(server);
076: * f.login(username, password);
077: * FTPFile[] files = f.listFiles(
078: * "org.apache.commons.net.ftp.parser.EnterpriseUnixFTPFileEntryParser",
079: * ".");
080: * </pre>
081: *
082: * The fourth example uses the revised <code>FTPClient.listFiles()</code>
083: * API to pull a single file listing in an arbitrary directory in one call,
084: * specifying by KEY the parser to be used, in this case, VMS.
085: *
086: * <pre>
087: * FTPClient f=FTPClient();
088: * f.connect(server);
089: * f.login(username, password);
090: * FTPFile[] files = f.listFiles("VMS", "subfolder/foo.java");
091: * </pre>
092: *
093: * @author <a href="mailto:scohen@apache.org">Steve Cohen</a>
094: * @version $Id: FTPFileEntryParser.java 165675 2005-05-02 20:09:55Z rwinston $
095: * @see org.apache.commons.net.ftp.FTPFile
096: * @see org.apache.commons.net.ftp.FTPClient#createFileList
097: */
098: public interface FTPFileEntryParser {
099: /**
100: * Parses a line of an FTP server file listing and converts it into a usable
101: * format in the form of an <code> FTPFile </code> instance. If the
102: * file listing line doesn't describe a file, <code> null </code> should be
103: * returned, otherwise a <code> FTPFile </code> instance representing the
104: * files in the directory is returned.
105: * <p>
106: * @param listEntry A line of text from the file listing
107: * @return An FTPFile instance corresponding to the supplied entry
108: */
109: FTPFile parseFTPEntry(String listEntry);
110:
111: /**
112: * Reads the next entry using the supplied BufferedReader object up to
113: * whatever delemits one entry from the next. Implementors must define
114: * this for the particular ftp system being parsed. In many but not all
115: * cases, this can be defined simply by calling BufferedReader.readLine().
116: *
117: * @param reader The BufferedReader object from which entries are to be
118: * read.
119: *
120: * @return A string representing the next ftp entry or null if none found.
121: * @exception IOException thrown on any IO Error reading from the reader.
122: */
123: String readNextEntry(BufferedReader reader) throws IOException;
124:
125: /**
126: * This method is a hook for those implementors (such as
127: * VMSVersioningFTPEntryParser, and possibly others) which need to
128: * perform some action upon the FTPFileList after it has been created
129: * from the server stream, but before any clients see the list.
130: *
131: * The default implementation can be a no-op.
132: *
133: * @param original Original list after it has been created from the server stream
134: *
135: * @return Original list as processed by this method.
136: */
137: List preParse(List original);
138:
139: }
140:
141: /* Emacs configuration
142: * Local variables: **
143: * mode: java **
144: * c-basic-offset: 4 **
145: * indent-tabs-mode: nil **
146: * End: **
147: */
|