    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     *
    035     * The first example uses the <code>FTPClient.listFiles()</code>
    036     * API to pull the whole list from the subfolder <code>subfolder</code> in
    037     * one call, attempting to automatically detect the parser type.  This
    038     * method, without a parserKey parameter, indicates that autodection should
    039     * be used.
    040     *
    041     * <pre>
    042     *    FTPClient f=FTPClient();
    043     *    f.connect(server);
    044     *    f.login(username, password);
    045     *    FTPFile[] files = f.listFiles("subfolder");
    046     * </pre>
    047     *
    048     * The secondr example uses the <code>FTPClient.listFiles()</code>>
    049     * API to pull the whole list from the current working directory in one call,
    050     * but specifying by classname the parser to be used.  For this particular
    051     * parser class, this approach is necessary since there is no way to
    052     * autodetect this server type.
    053     *
    054     * <pre>
    055     *    FTPClient f=FTPClient();
    056     *    f.connect(server);
    057     *    f.login(username, password);
    058     *    FTPFile[] files = f.listFiles(
    059     *      "org.apache.commons.net.ftp.parser.EnterpriseUnixFTPFileEntryParser",
    060     *      ".");
    061     * </pre>
    062     *
    063     * The third example uses the <code>FTPClient.listFiles()</code>
    064     * API to pull a single file listing in an arbitrary directory in one call,
    065     * specifying by KEY the parser to be used, in this case, VMS.
    066     *
    067     * <pre>
    068     *    FTPClient f=FTPClient();
    069     *    f.connect(server);
    070     *    f.login(username, password);
    071     *    FTPFile[] files = f.listFiles("VMS", "subfolder/foo.java");
    072     * </pre>
    073     *
    074     * For an alternative approach, see the {@link FTPListParseEngine} class
    075     * which provides iterative access.
    076     *
    077     * @author <a href="mailto:scohen@apache.org">Steve Cohen</a>
    078     * @version $Id: FTPFileEntryParser.java 1081475 2011-03-14 17:07:53Z sebb $
    079     * @see org.apache.commons.net.ftp.FTPFile
    080     * @see org.apache.commons.net.ftp.FTPClient#listFiles()
    081     */
    082    public interface FTPFileEntryParser
    083    {
    084        /**
    085         * Parses a line of an FTP server file listing and converts it into a usable
    086         * format in the form of an <code> FTPFile </code> instance.  If the
    087         * file listing line doesn't describe a file, <code> null </code> should be
    088         * returned, otherwise a <code> FTPFile </code> instance representing the
    089         * files in the directory is returned.
    090         * <p>
    091         * @param listEntry A line of text from the file listing
    092         * @return An FTPFile instance corresponding to the supplied entry
    093         */
    094        FTPFile parseFTPEntry(String listEntry);
    095
    096        /**
    097         * Reads the next entry using the supplied BufferedReader object up to
    098         * whatever delemits one entry from the next.  Implementors must define
    099         * this for the particular ftp system being parsed.  In many but not all
    100         * cases, this can be defined simply by calling BufferedReader.readLine().
    101         *
    102         * @param reader The BufferedReader object from which entries are to be
    103         * read.
    104         *
    105         * @return A string representing the next ftp entry or null if none found.
    106         * @exception IOException thrown on any IO Error reading from the reader.
    107         */
    108        String readNextEntry(BufferedReader reader) throws IOException;
    109
    110
    111        /**
    112         * This method is a hook for those implementors (such as
    113         * VMSVersioningFTPEntryParser, and possibly others) which need to
    114         * perform some action upon the FTPFileList after it has been created
    115         * from the server stream, but before any clients see the list.
    116         *
    117         * The default implementation can be a no-op.
    118         *
    119         * @param original Original list after it has been created from the server stream
    120         *
    121         * @return Original list as processed by this method.
    122         */
    123        List<String> preParse(List<String> original);
    124
    125
    126    }
    127
    128
    129    /* Emacs configuration
    130     * Local variables:        **
    131     * mode:             java  **
    132     * c-basic-offset:   4     **
    133     * indent-tabs-mode: nil   **
    134     * End:                    **
    135     */