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 import java.io.BufferedReader;
018 import java.io.IOException;
019 import java.util.List;
020
021 /**
022 * FTPFileEntryParser defines the interface for parsing a single FTP file
023 * listing and converting that information into an
024 * {@link org.apache.commons.net.ftp.FTPFile} instance.
025 * Sometimes you will want to parse unusual listing formats, in which
026 * case you would create your own implementation of FTPFileEntryParser and
027 * if necessary, subclass FTPFile.
028 * <p>
029 * Here are some examples showing how to use one of the classes that
030 * implement this interface.
031 * <p>
032 * The first example shows how to get an <b>iterable</b> list of files in which the
033 * more expensive <code>FTPFile</code> objects are not created until needed. This
034 * is suitable for paged displays. It requires that a parser object be created
035 * beforehand: <code>parser</code> is an object (in the package
036 * <code>org.apache.commons.net.ftp.parser</code>)
037 * implementing this inteface.
038 *
039 * <pre>
040 * FTPClient f=FTPClient();
041 * f.connect(server);
042 * f.login(username, password);
043 * FTPFileList list = f.createFileList(directory, parser);
044 * FTPFileIterator iter = list.iterator();
045 *
046 * while (iter.hasNext()) {
047 * FTPFile[] files = iter.getNext(25); // "page size" you want
048 * //do whatever you want with these files, display them, etc.
049 * //expensive FTPFile objects not created until needed.
050 * }
051 * </pre>
052 *
053 * The second example uses the revised <code>FTPClient.listFiles()</code>
054 * API to pull the whole list from the subfolder <code>subfolder</code> in
055 * one call, attempting to automatically detect the parser type. This
056 * method, without a parserKey parameter, indicates that autodection should
057 * be used.
058 *
059 * <pre>
060 * FTPClient f=FTPClient();
061 * f.connect(server);
062 * f.login(username, password);
063 * FTPFile[] files = f.listFiles("subfolder");
064 * </pre>
065 *
066 * The third example uses the revised <code>FTPClient.listFiles()</code>>
067 * API to pull the whole list from the current working directory in one call,
068 * but specifying by classname the parser to be used. For this particular
069 * parser class, this approach is necessary since there is no way to
070 * autodetect this server type.
071 *
072 * <pre>
073 * FTPClient f=FTPClient();
074 * f.connect(server);
075 * f.login(username, password);
076 * FTPFile[] files = f.listFiles(
077 * "org.apache.commons.net.ftp.parser.EnterpriseUnixFTPFileEntryParser",
078 * ".");
079 * </pre>
080 *
081 * The fourth example uses the revised <code>FTPClient.listFiles()</code>
082 * API to pull a single file listing in an arbitrary directory in one call,
083 * specifying by KEY the parser to be used, in this case, VMS.
084 *
085 * <pre>
086 * FTPClient f=FTPClient();
087 * f.connect(server);
088 * f.login(username, password);
089 * FTPFile[] files = f.listFiles("VMS", "subfolder/foo.java");
090 * </pre>
091 *
092 * @author <a href="mailto:scohen@apache.org">Steve Cohen</a>
093 * @version $Id: FTPFileEntryParser.java 165675 2005-05-02 20:09:55Z rwinston $
094 * @see org.apache.commons.net.ftp.FTPFile
095 * @see org.apache.commons.net.ftp.FTPClient#createFileList
096 */
097 public interface FTPFileEntryParser
098 {
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 /**
127 * This method is a hook for those implementors (such as
128 * VMSVersioningFTPEntryParser, and possibly others) which need to
129 * perform some action upon the FTPFileList after it has been created
130 * from the server stream, but before any clients see the list.
131 *
132 * The default implementation can be a no-op.
133 *
134 * @param original Original list after it has been created from the server stream
135 *
136 * @return Original list as processed by this method.
137 */
138 List preParse(List original);
139
140
141 }
142
143
144 /* Emacs configuration
145 * Local variables: **
146 * mode: java **
147 * c-basic-offset: 4 **
148 * indent-tabs-mode: nil **
149 * End: **
150 */