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    
018    package org.apache.commons.net.ftp;
019    import java.io.BufferedReader;
020    import java.io.IOException;
021    import 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 748376 2009-02-27 01:57:19Z sebb $
096     * @see org.apache.commons.net.ftp.FTPFile
097     * @see org.apache.commons.net.ftp.FTPClient#listFiles()
098     */
099    public 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     */