1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * https://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package org.apache.commons.net.ftp; 19 20 import java.io.BufferedReader; 21 import java.io.IOException; 22 import java.util.List; 23 24 /** 25 * FTPFileEntryParser defines the interface for parsing a single FTP file listing and converting that information into an 26 * {@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 27 * implementation of FTPFileEntryParser and if necessary, subclass FTPFile. 28 * <p> 29 * Here are some examples showing how to use one of the classes that implement this interface. 30 * </p> 31 * <p> 32 * The first example uses the {@code FTPClient.listFiles()} API to pull the whole list from the subfolder {@code subfolder} in one call, attempting to 33 * automatically detect the parser type. This method, without a parserKey parameter, indicates that autodection should be used. 34 * </p> 35 * 36 * <pre> 37 * FTPClient f = FTPClient(); 38 * f.connect(server); 39 * f.login(user, password); 40 * FTPFile[] files = f.listFiles("subfolder"); 41 * </pre> 42 * 43 * 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 44 * 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. 45 * 46 * <pre> 47 * FTPClient f = FTPClient(); 48 * f.connect(server); 49 * f.login(user, password); 50 * FTPFile[] files = f.listFiles("org.apache.commons.net.ftp.parser.EnterpriseUnixFTPFileEntryParser", "."); 51 * </pre> 52 * 53 * 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 54 * parser to be used, in this case, VMS. 55 * 56 * <pre> 57 * FTPClient f = FTPClient(); 58 * f.connect(server); 59 * f.login(user, password); 60 * FTPFile[] files = f.listFiles("VMS", "subfolder/foo.java"); 61 * </pre> 62 * <p> 63 * For an alternative approach, see the {@link FTPListParseEngine} class which provides iterative access. 64 * </p> 65 * 66 * @see org.apache.commons.net.ftp.FTPFile 67 * @see org.apache.commons.net.ftp.FTPClient#listFiles() 68 */ 69 public interface FTPFileEntryParser { 70 71 /** 72 * 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 73 * line doesn't describe a file, {@code null} should be returned, otherwise a {@code FTPFile} instance representing the files in the directory 74 * is returned. 75 * 76 * @param listEntry A line of text from the file listing 77 * @return An FTPFile instance corresponding to the supplied entry 78 */ 79 FTPFile parseFTPEntry(String listEntry); 80 81 /** 82 * This method is a hook for those implementors (such as VMSVersioningFTPEntryParser, and possibly others) which need to perform some action upon the 83 * FTPFileList after it has been created from the server stream, but before any clients see the list. 84 * 85 * The default implementation can be a no-op. 86 * 87 * @param original Original list after it has been created from the server stream 88 * @return Original list as processed by this method. 89 */ 90 List<String> preParse(List<String> original); 91 92 /** 93 * Reads the next entry using the supplied BufferedReader object up to whatever delimits one entry from the next. Implementors must define this for the 94 * particular ftp system being parsed. In many but not all cases, this can be defined simply by calling BufferedReader.readLine(). 95 * 96 * @param reader The BufferedReader object from which entries are to be read. 97 * @return A string representing the next ftp entry or null if none found. 98 * @throws IOException thrown on any IO Error reading from the reader. 99 */ 100 String readNextEntry(BufferedReader reader) throws IOException; 101 102 }