    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 *
    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 1299238 2012-03-10 17:12:28Z sebb $
    079 * @see org.apache.commons.net.ftp.FTPFile
    080 * @see org.apache.commons.net.ftp.FTPClient#listFiles()
    081 */
    082public 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 */