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 * http://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 import java.io.BufferedReader; 20 import java.io.IOException; 21 import java.util.List; 22 23 /** 24 * FTPFileEntryParser defines the interface for parsing a single FTP file 25 * listing and converting that information into an 26 * {@link org.apache.commons.net.ftp.FTPFile} instance. 27 * Sometimes you will want to parse unusual listing formats, in which 28 * case you would create your own implementation of FTPFileEntryParser and 29 * if necessary, subclass FTPFile. 30 * <p> 31 * Here are some examples showing how to use one of the classes that 32 * implement this interface. 33 * <p> 34 * 35 * The first example uses the <code>FTPClient.listFiles()</code> 36 * API to pull the whole list from the subfolder <code>subfolder</code> in 37 * one call, attempting to automatically detect the parser type. This 38 * method, without a parserKey parameter, indicates that autodection should 39 * be used. 40 * 41 * <pre> 42 * FTPClient f=FTPClient(); 43 * f.connect(server); 44 * f.login(username, password); 45 * FTPFile[] files = f.listFiles("subfolder"); 46 * </pre> 47 * 48 * The secondr example uses the <code>FTPClient.listFiles()</code>> 49 * API to pull the whole list from the current working directory in one call, 50 * but specifying by classname the parser to be used. For this particular 51 * parser class, this approach is necessary since there is no way to 52 * autodetect this server type. 53 * 54 * <pre> 55 * FTPClient f=FTPClient(); 56 * f.connect(server); 57 * f.login(username, password); 58 * FTPFile[] files = f.listFiles( 59 * "org.apache.commons.net.ftp.parser.EnterpriseUnixFTPFileEntryParser", 60 * "."); 61 * </pre> 62 * 63 * The third example uses the <code>FTPClient.listFiles()</code> 64 * API to pull a single file listing in an arbitrary directory in one call, 65 * specifying by KEY the parser to be used, in this case, VMS. 66 * 67 * <pre> 68 * FTPClient f=FTPClient(); 69 * f.connect(server); 70 * f.login(username, password); 71 * FTPFile[] files = f.listFiles("VMS", "subfolder/foo.java"); 72 * </pre> 73 * 74 * For an alternative approach, see the {@link FTPListParseEngine} class 75 * which provides iterative access. 76 * 77 * @author <a href="mailto:scohen@apache.org">Steve Cohen</a> 78 * @version $Id: FTPFileEntryParser.java 1299238 2012-03-10 17:12:28Z sebb $ 79 * @see org.apache.commons.net.ftp.FTPFile 80 * @see org.apache.commons.net.ftp.FTPClient#listFiles() 81 */ 82 public interface FTPFileEntryParser 83 { 84 /** 85 * Parses a line of an FTP server file listing and converts it into a usable 86 * format in the form of an <code> FTPFile </code> instance. If the 87 * file listing line doesn't describe a file, <code> null </code> should be 88 * returned, otherwise a <code> FTPFile </code> instance representing the 89 * files in the directory is returned. 90 * <p> 91 * @param listEntry A line of text from the file listing 92 * @return An FTPFile instance corresponding to the supplied entry 93 */ 94 FTPFile parseFTPEntry(String listEntry); 95 96 /** 97 * Reads the next entry using the supplied BufferedReader object up to 98 * whatever delemits one entry from the next. Implementors must define 99 * 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 */