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