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