    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;
    019
    020import java.io.BufferedReader;
    021import java.io.IOException;
    022import java.util.List;
    023
    024/**
    025 * FTPFileEntryParser defines the interface for parsing a single FTP file listing and converting that information into an
    026 * {@link org.apache.commons.net.ftp.FTPFile} instance. Sometimes you will want to parse unusual listing formats, in which case you would create your own
    027 * implementation of FTPFileEntryParser and if necessary, subclass FTPFile.
    028 * <p>
    029 * Here are some examples showing how to use one of the classes that implement this interface.
    030 * <p>
    031 *
    032 * The first example uses the <code>FTPClient.listFiles()</code> API to pull the whole list from the subfolder <code>subfolder</code> in one call, attempting to
    033 * automatically detect the parser type. This method, without a parserKey parameter, indicates that autodection should be used.
    034 *
    035 * <pre>
    036 * FTPClient f = FTPClient();
    037 * f.connect(server);
    038 * f.login(user, password);
    039 * FTPFile[] files = f.listFiles("subfolder");
    040 * </pre>
    041 *
    042 * The second example uses the <code>FTPClient.listFiles()</code> API to pull the whole list from the current working directory in one call, but specifying by
    043 * classname the parser to be used. For this particular parser class, this approach is necessary since there is no way to autodetect this server type.
    044 *
    045 * <pre>
    046 * FTPClient f = FTPClient();
    047 * f.connect(server);
    048 * f.login(user, password);
    049 * FTPFile[] files = f.listFiles("org.apache.commons.net.ftp.parser.EnterpriseUnixFTPFileEntryParser", ".");
    050 * </pre>
    051 *
    052 * The third example uses the <code>FTPClient.listFiles()</code> API to pull a single file listing in an arbitrary directory in one call, specifying by KEY the
    053 * parser to be used, in this case, VMS.
    054 *
    055 * <pre>
    056 * FTPClient f = FTPClient();
    057 * f.connect(server);
    058 * f.login(user, password);
    059 * FTPFile[] files = f.listFiles("VMS", "subfolder/foo.java");
    060 * </pre>
    061 *
    062 * For an alternative approach, see the {@link FTPListParseEngine} class which provides iterative access.
    063 *
    064 * @see org.apache.commons.net.ftp.FTPFile
    065 * @see org.apache.commons.net.ftp.FTPClient#listFiles()
    066 */
    067public interface FTPFileEntryParser {
    068    /**
    069     * Parses a line of an FTP server file listing and converts it into a usable format in the form of an <code> FTPFile </code> instance. If the file listing
    070     * line doesn't describe a file, <code> null </code> should be returned, otherwise a <code> FTPFile </code> instance representing the files in the directory
    071     * is returned.
    072     *
    073     * @param listEntry A line of text from the file listing
    074     * @return An FTPFile instance corresponding to the supplied entry
    075     */
    076    FTPFile parseFTPEntry(String listEntry);
    077
    078    /**
    079     * This method is a hook for those implementors (such as VMSVersioningFTPEntryParser, and possibly others) which need to perform some action upon the
    080     * FTPFileList after it has been created from the server stream, but before any clients see the list.
    081     *
    082     * The default implementation can be a no-op.
    083     *
    084     * @param original Original list after it has been created from the server stream
    085     *
    086     * @return Original list as processed by this method.
    087     */
    088    List<String> preParse(List<String> original);
    089
    090    /**
    091     * Reads the next entry using the supplied BufferedReader object up to whatever delimits one entry from the next. Implementors must define this for the
    092     * particular ftp system being parsed. In many but not all cases, this can be defined simply by calling BufferedReader.readLine().
    093     *
    094     * @param reader The BufferedReader object from which entries are to be read.
    095     *
    096     * @return A string representing the next ftp entry or null if none found.
    097     * @throws IOException thrown on any IO Error reading from the reader.
    098     */
    099    String readNextEntry(BufferedReader reader) throws IOException;
    100
    101}